Repository: coleam00/Archon Branch: main Commit: ecaece460c19 Files: 674 Total size: 4.6 MB Directory structure: gitextract_rpa0i55w/ ├── .claude/ │ ├── agents/ │ │ ├── codebase-analyst.md │ │ └── library-researcher.md │ └── commands/ │ ├── agent-work-orders/ │ │ ├── commit.md │ │ ├── execute.md │ │ ├── noqa.md │ │ ├── planning.md │ │ ├── prime.md │ │ ├── prp-review.md │ │ └── start-server.md │ ├── archon/ │ │ ├── archon-alpha-review.md │ │ ├── archon-coderabbit-helper.md │ │ ├── archon-onboarding.md │ │ ├── archon-prime-simple.md │ │ ├── archon-prime.md │ │ ├── archon-rca.md │ │ └── archon-ui-consistency-review.md │ ├── prp-any-agent/ │ │ ├── prp-any-cli-create.md │ │ └── prp-any-cli-execute.md │ └── prp-claude-code/ │ ├── prp-claude-code-create.md │ ├── prp-claude-code-execute.md │ ├── prp-story-task-create.md │ └── prp-story-task-execute.md ├── .dockerignore ├── .github/ │ ├── ISSUE_TEMPLATE/ │ │ ├── auto_bug_report.md │ │ └── bug_report.yml │ ├── RELEASE_NOTES_SETUP.md │ ├── pull_request_template.md │ ├── test-release-notes.sh │ └── workflows/ │ ├── ci.yml │ ├── claude-fix.yml │ ├── claude-review.yml │ └── release-notes.yml ├── .gitignore ├── AGENTS.md ├── CLAUDE.md ├── CONTRIBUTING.md ├── LICENSE ├── Makefile ├── PRPs/ │ ├── ai_docs/ │ │ ├── AGENT_WORK_ORDERS_SSE_AND_ZUSTAND.md │ │ ├── API_NAMING_CONVENTIONS.md │ │ ├── ARCHITECTURE.md │ │ ├── DATA_FETCHING_ARCHITECTURE.md │ │ ├── ETAG_IMPLEMENTATION.md │ │ ├── QUERY_PATTERNS.md │ │ ├── UI_STANDARDS.md │ │ ├── ZUSTAND_STATE_MANAGEMENT.md │ │ ├── cc_cli_ref.md │ │ └── optimistic_updates.md │ └── templates/ │ ├── prp_base.md │ └── prp_story_task.md ├── README.md ├── archon-example-workflow/ │ ├── .claude/ │ │ ├── agents/ │ │ │ ├── codebase-analyst.md │ │ │ └── validator.md │ │ └── commands/ │ │ ├── create-plan.md │ │ ├── execute-plan.md │ │ └── primer.md │ ├── CLAUDE.md │ └── README.md ├── archon-ui-main/ │ ├── .dockerignore │ ├── .eslintrc.cjs │ ├── .gitignore │ ├── Dockerfile │ ├── README.md │ ├── biome.json │ ├── index.html │ ├── package.json │ ├── postcss.config.js │ ├── src/ │ │ ├── App.tsx │ │ ├── components/ │ │ │ ├── BackendStartupError.tsx │ │ │ ├── DisconnectScreenOverlay.tsx │ │ │ ├── agent-chat/ │ │ │ │ └── ArchonChatPanel.tsx │ │ │ ├── animations/ │ │ │ │ ├── Animations.tsx │ │ │ │ └── DisconnectScreenAnimations.tsx │ │ │ ├── bug-report/ │ │ │ │ ├── BugReportButton.tsx │ │ │ │ ├── BugReportModal.tsx │ │ │ │ └── ErrorBoundaryWithBugReport.tsx │ │ │ ├── code/ │ │ │ │ └── CodeViewerModal.tsx │ │ │ ├── common/ │ │ │ │ └── DeleteConfirmModal.tsx │ │ │ ├── layout/ │ │ │ │ ├── MainLayout.tsx │ │ │ │ ├── Navigation.tsx │ │ │ │ ├── hooks/ │ │ │ │ │ └── useBackendHealth.ts │ │ │ │ ├── index.ts │ │ │ │ └── types.ts │ │ │ ├── onboarding/ │ │ │ │ └── ProviderStep.tsx │ │ │ ├── settings/ │ │ │ │ ├── APIKeysSection.tsx │ │ │ │ ├── ButtonPlayground.tsx │ │ │ │ ├── CodeExtractionSettings.tsx │ │ │ │ ├── FeaturesSection.tsx │ │ │ │ ├── IDEGlobalRules.tsx │ │ │ │ ├── OllamaConfigurationPanel.tsx │ │ │ │ ├── OllamaInstanceHealthIndicator.tsx │ │ │ │ ├── OllamaModelDiscoveryModal.tsx │ │ │ │ ├── OllamaModelSelectionModal.tsx │ │ │ │ ├── RAGSettings.tsx │ │ │ │ └── types/ │ │ │ │ └── OllamaTypes.ts │ │ │ └── ui/ │ │ │ ├── Badge.tsx │ │ │ ├── Button.tsx │ │ │ ├── Card.tsx │ │ │ ├── Checkbox.tsx │ │ │ ├── CollapsibleSettingsCard.tsx │ │ │ ├── CoverageVisualization.tsx │ │ │ ├── GlassCrawlDepthSelector.tsx │ │ │ ├── Input.tsx │ │ │ ├── MigrationBanner.tsx │ │ │ ├── NeonButton.tsx │ │ │ ├── PowerButton.tsx │ │ │ ├── Select.tsx │ │ │ ├── ThemeToggle.tsx │ │ │ └── Toggle.tsx │ │ ├── config/ │ │ │ └── api.ts │ │ ├── contexts/ │ │ │ ├── SettingsContext.tsx │ │ │ └── ThemeContext.tsx │ │ ├── env.d.ts │ │ ├── features/ │ │ │ ├── agent-work-orders/ │ │ │ │ ├── components/ │ │ │ │ │ ├── AddRepositoryModal.tsx │ │ │ │ │ ├── CreateWorkOrderModal.tsx │ │ │ │ │ ├── EditRepositoryModal.tsx │ │ │ │ │ ├── ExecutionLogs.tsx │ │ │ │ │ ├── RealTimeStats.tsx │ │ │ │ │ ├── RepositoryCard.tsx │ │ │ │ │ ├── SidebarRepositoryCard.tsx │ │ │ │ │ ├── StepHistoryCard.tsx │ │ │ │ │ ├── WorkOrderRow.tsx │ │ │ │ │ ├── WorkOrderTable.tsx │ │ │ │ │ ├── WorkflowStepButton.tsx │ │ │ │ │ └── __tests__/ │ │ │ │ │ ├── CreateWorkOrderModal.test.tsx │ │ │ │ │ └── RepositoryCard.test.tsx │ │ │ │ ├── hooks/ │ │ │ │ │ ├── __tests__/ │ │ │ │ │ │ ├── useAgentWorkOrderQueries.test.tsx │ │ │ │ │ │ └── useRepositoryQueries.test.tsx │ │ │ │ │ ├── useAgentWorkOrderQueries.ts │ │ │ │ │ └── useRepositoryQueries.ts │ │ │ │ ├── services/ │ │ │ │ │ ├── __tests__/ │ │ │ │ │ │ ├── agentWorkOrdersService.test.ts │ │ │ │ │ │ └── repositoryService.test.ts │ │ │ │ │ ├── agentWorkOrdersService.ts │ │ │ │ │ └── repositoryService.ts │ │ │ │ ├── state/ │ │ │ │ │ ├── __tests__/ │ │ │ │ │ │ ├── agentWorkOrdersStore.test.ts │ │ │ │ │ │ └── sseIntegration.test.ts │ │ │ │ │ ├── agentWorkOrdersStore.ts │ │ │ │ │ └── slices/ │ │ │ │ │ ├── filtersSlice.ts │ │ │ │ │ ├── modalsSlice.ts │ │ │ │ │ ├── sseSlice.ts │ │ │ │ │ └── uiPreferencesSlice.ts │ │ │ │ ├── types/ │ │ │ │ │ ├── index.ts │ │ │ │ │ └── repository.ts │ │ │ │ └── views/ │ │ │ │ ├── AgentWorkOrderDetailView.tsx │ │ │ │ └── AgentWorkOrdersView.tsx │ │ │ ├── knowledge/ │ │ │ │ ├── components/ │ │ │ │ │ ├── AddKnowledgeDialog.tsx │ │ │ │ │ ├── KnowledgeCard.tsx │ │ │ │ │ ├── KnowledgeCardActions.tsx │ │ │ │ │ ├── KnowledgeCardTags.tsx │ │ │ │ │ ├── KnowledgeCardTitle.tsx │ │ │ │ │ ├── KnowledgeCardType.tsx │ │ │ │ │ ├── KnowledgeHeader.tsx │ │ │ │ │ ├── KnowledgeList.tsx │ │ │ │ │ ├── KnowledgeTable.tsx │ │ │ │ │ ├── KnowledgeTypeSelector.tsx │ │ │ │ │ ├── LevelSelector.tsx │ │ │ │ │ ├── TagInput.tsx │ │ │ │ │ └── index.ts │ │ │ │ ├── hooks/ │ │ │ │ │ ├── index.ts │ │ │ │ │ ├── tests/ │ │ │ │ │ │ └── useKnowledgeQueries.test.ts │ │ │ │ │ └── useKnowledgeQueries.ts │ │ │ │ ├── index.ts │ │ │ │ ├── inspector/ │ │ │ │ │ ├── components/ │ │ │ │ │ │ ├── ContentViewer.tsx │ │ │ │ │ │ ├── InspectorHeader.tsx │ │ │ │ │ │ ├── InspectorSidebar.tsx │ │ │ │ │ │ ├── KnowledgeInspector.tsx │ │ │ │ │ │ └── index.ts │ │ │ │ │ ├── hooks/ │ │ │ │ │ │ ├── index.ts │ │ │ │ │ │ ├── useInspectorData.ts │ │ │ │ │ │ ├── useInspectorPagination.ts │ │ │ │ │ │ └── usePaginatedInspectorData.ts │ │ │ │ │ └── index.ts │ │ │ │ ├── services/ │ │ │ │ │ ├── index.ts │ │ │ │ │ └── knowledgeService.ts │ │ │ │ ├── types/ │ │ │ │ │ ├── index.ts │ │ │ │ │ └── knowledge.ts │ │ │ │ ├── utils/ │ │ │ │ │ ├── index.ts │ │ │ │ │ ├── knowledge-utils.ts │ │ │ │ │ ├── providerErrorHandler.ts │ │ │ │ │ └── tests/ │ │ │ │ │ └── providerErrorHandler.test.ts │ │ │ │ └── views/ │ │ │ │ ├── KnowledgeView.tsx │ │ │ │ ├── KnowledgeViewWithBoundary.tsx │ │ │ │ └── index.ts │ │ │ ├── mcp/ │ │ │ │ ├── components/ │ │ │ │ │ ├── McpClientList.tsx │ │ │ │ │ ├── McpConfigSection.tsx │ │ │ │ │ ├── McpStatusBar.tsx │ │ │ │ │ └── index.ts │ │ │ │ ├── hooks/ │ │ │ │ │ ├── index.ts │ │ │ │ │ └── useMcpQueries.ts │ │ │ │ ├── index.ts │ │ │ │ ├── services/ │ │ │ │ │ ├── index.ts │ │ │ │ │ └── mcpApi.ts │ │ │ │ ├── types/ │ │ │ │ │ ├── index.ts │ │ │ │ │ └── mcp.ts │ │ │ │ └── views/ │ │ │ │ ├── McpView.tsx │ │ │ │ └── McpViewWithBoundary.tsx │ │ │ ├── progress/ │ │ │ │ ├── components/ │ │ │ │ │ ├── CrawlingProgress.tsx │ │ │ │ │ ├── KnowledgeCardProgress.tsx │ │ │ │ │ └── index.ts │ │ │ │ ├── hooks/ │ │ │ │ │ ├── index.ts │ │ │ │ │ ├── tests/ │ │ │ │ │ │ └── useProgressQueries.test.ts │ │ │ │ │ └── useProgressQueries.ts │ │ │ │ ├── index.ts │ │ │ │ ├── services/ │ │ │ │ │ ├── index.ts │ │ │ │ │ └── progressService.ts │ │ │ │ ├── types/ │ │ │ │ │ ├── index.ts │ │ │ │ │ └── progress.ts │ │ │ │ └── utils/ │ │ │ │ └── urlValidation.ts │ │ │ ├── projects/ │ │ │ │ ├── components/ │ │ │ │ │ ├── NewProjectModal.tsx │ │ │ │ │ ├── ProjectCard.tsx │ │ │ │ │ ├── ProjectCardActions.tsx │ │ │ │ │ ├── ProjectHeader.tsx │ │ │ │ │ ├── ProjectList.tsx │ │ │ │ │ ├── index.ts │ │ │ │ │ └── tests/ │ │ │ │ │ └── ProjectCard.test.tsx │ │ │ │ ├── documents/ │ │ │ │ │ ├── DocsTab.tsx │ │ │ │ │ ├── components/ │ │ │ │ │ │ ├── AddDocumentModal.tsx │ │ │ │ │ │ ├── DocumentCard.tsx │ │ │ │ │ │ ├── DocumentViewer.tsx │ │ │ │ │ │ └── index.ts │ │ │ │ │ ├── hooks/ │ │ │ │ │ │ ├── index.ts │ │ │ │ │ │ └── useDocumentQueries.ts │ │ │ │ │ ├── index.ts │ │ │ │ │ ├── services/ │ │ │ │ │ │ └── documentService.ts │ │ │ │ │ └── types/ │ │ │ │ │ ├── document.ts │ │ │ │ │ └── index.ts │ │ │ │ ├── hooks/ │ │ │ │ │ ├── index.ts │ │ │ │ │ ├── tests/ │ │ │ │ │ │ └── useProjectQueries.test.ts │ │ │ │ │ └── useProjectQueries.ts │ │ │ │ ├── index.ts │ │ │ │ ├── schemas/ │ │ │ │ │ └── index.ts │ │ │ │ ├── services/ │ │ │ │ │ ├── index.ts │ │ │ │ │ └── projectService.ts │ │ │ │ ├── shared/ │ │ │ │ │ └── api.ts │ │ │ │ ├── tasks/ │ │ │ │ │ ├── TasksTab.tsx │ │ │ │ │ ├── components/ │ │ │ │ │ │ ├── EditableTableCell.tsx │ │ │ │ │ │ ├── FeatureSelect.tsx │ │ │ │ │ │ ├── KanbanColumn.tsx │ │ │ │ │ │ ├── TaskAssignee.tsx │ │ │ │ │ │ ├── TaskCard.tsx │ │ │ │ │ │ ├── TaskCardActions.tsx │ │ │ │ │ │ ├── TaskEditModal.tsx │ │ │ │ │ │ ├── TaskPriorityComponent.tsx │ │ │ │ │ │ └── index.ts │ │ │ │ │ ├── hooks/ │ │ │ │ │ │ ├── index.ts │ │ │ │ │ │ ├── tests/ │ │ │ │ │ │ │ └── useTaskQueries.test.ts │ │ │ │ │ │ ├── useTaskActions.ts │ │ │ │ │ │ ├── useTaskEditor.ts │ │ │ │ │ │ └── useTaskQueries.ts │ │ │ │ │ ├── index.ts │ │ │ │ │ ├── schemas/ │ │ │ │ │ │ └── index.ts │ │ │ │ │ ├── services/ │ │ │ │ │ │ ├── index.ts │ │ │ │ │ │ ├── taskService.ts │ │ │ │ │ │ └── tests/ │ │ │ │ │ │ └── taskService.test.ts │ │ │ │ │ ├── types/ │ │ │ │ │ │ ├── hooks.ts │ │ │ │ │ │ ├── index.ts │ │ │ │ │ │ ├── priority.ts │ │ │ │ │ │ └── task.ts │ │ │ │ │ ├── utils/ │ │ │ │ │ │ ├── index.ts │ │ │ │ │ │ ├── task-ordering.ts │ │ │ │ │ │ └── task-styles.tsx │ │ │ │ │ └── views/ │ │ │ │ │ ├── BoardView.tsx │ │ │ │ │ ├── TableView.tsx │ │ │ │ │ └── index.ts │ │ │ │ ├── types/ │ │ │ │ │ ├── index.ts │ │ │ │ │ └── project.ts │ │ │ │ ├── utils/ │ │ │ │ │ └── index.ts │ │ │ │ └── views/ │ │ │ │ ├── ProjectsView.tsx │ │ │ │ └── ProjectsViewWithBoundary.tsx │ │ │ ├── settings/ │ │ │ │ ├── migrations/ │ │ │ │ │ ├── components/ │ │ │ │ │ │ ├── MigrationStatusCard.tsx │ │ │ │ │ │ └── PendingMigrationsModal.tsx │ │ │ │ │ ├── hooks/ │ │ │ │ │ │ └── useMigrationQueries.ts │ │ │ │ │ ├── services/ │ │ │ │ │ │ └── migrationService.ts │ │ │ │ │ └── types/ │ │ │ │ │ └── index.ts │ │ │ │ └── version/ │ │ │ │ ├── components/ │ │ │ │ │ ├── UpdateBanner.tsx │ │ │ │ │ └── VersionStatusCard.tsx │ │ │ │ ├── hooks/ │ │ │ │ │ └── useVersionQueries.ts │ │ │ │ ├── services/ │ │ │ │ │ └── versionService.ts │ │ │ │ └── types/ │ │ │ │ └── index.ts │ │ │ ├── shared/ │ │ │ │ ├── api/ │ │ │ │ │ ├── apiClient.ts │ │ │ │ │ └── tests/ │ │ │ │ │ └── apiClient.test.ts │ │ │ │ ├── config/ │ │ │ │ │ ├── queryClient.ts │ │ │ │ │ └── queryPatterns.ts │ │ │ │ ├── hooks/ │ │ │ │ │ ├── index.ts │ │ │ │ │ ├── tests/ │ │ │ │ │ │ └── useSmartPolling.test.ts │ │ │ │ │ ├── useSmartPolling.ts │ │ │ │ │ ├── useThemeAware.ts │ │ │ │ │ └── useToast.ts │ │ │ │ ├── types/ │ │ │ │ │ └── errors.ts │ │ │ │ └── utils/ │ │ │ │ ├── clipboard.ts │ │ │ │ ├── optimistic.ts │ │ │ │ └── tests/ │ │ │ │ └── optimistic.test.ts │ │ │ ├── style-guide/ │ │ │ │ ├── components/ │ │ │ │ │ └── StyleGuideView.tsx │ │ │ │ ├── components.json │ │ │ │ ├── index.ts │ │ │ │ ├── layouts/ │ │ │ │ │ ├── AgentWorkOrderExample.tsx │ │ │ │ │ ├── AgentWorkOrderLayoutExample.tsx │ │ │ │ │ ├── DocumentBrowserExample.tsx │ │ │ │ │ ├── KnowledgeLayoutExample.tsx │ │ │ │ │ ├── NavigationExplanation.tsx │ │ │ │ │ ├── ProjectsLayoutExample.tsx │ │ │ │ │ ├── SettingsLayoutExample.tsx │ │ │ │ │ └── components/ │ │ │ │ │ ├── ExecutionLogsExample.tsx │ │ │ │ │ ├── RealTimeStatsExample.tsx │ │ │ │ │ ├── StepHistoryCard.tsx │ │ │ │ │ └── WorkflowStepButton.tsx │ │ │ │ ├── shared/ │ │ │ │ │ └── SideNavigation.tsx │ │ │ │ ├── showcases/ │ │ │ │ │ ├── StaticButtons.tsx │ │ │ │ │ ├── StaticCards.tsx │ │ │ │ │ ├── StaticColors.tsx │ │ │ │ │ ├── StaticEffects.tsx │ │ │ │ │ ├── StaticForms.tsx │ │ │ │ │ ├── StaticSpacing.tsx │ │ │ │ │ ├── StaticTables.tsx │ │ │ │ │ ├── StaticToggles.tsx │ │ │ │ │ └── StaticTypography.tsx │ │ │ │ ├── standards/ │ │ │ │ │ └── modalStandards.ts │ │ │ │ ├── tabs/ │ │ │ │ │ ├── LayoutsTab.tsx │ │ │ │ │ └── StyleGuideTab.tsx │ │ │ │ └── types/ │ │ │ │ └── index.ts │ │ │ ├── testing/ │ │ │ │ └── test-utils.tsx │ │ │ └── ui/ │ │ │ ├── components/ │ │ │ │ ├── DeleteConfirmModal.tsx │ │ │ │ ├── FeatureErrorBoundary.tsx │ │ │ │ ├── ToastProvider.tsx │ │ │ │ └── index.ts │ │ │ └── primitives/ │ │ │ ├── OptimisticIndicator.tsx │ │ │ ├── alert-dialog.tsx │ │ │ ├── button.tsx │ │ │ ├── card.tsx │ │ │ ├── checkbox.tsx │ │ │ ├── combobox.tsx │ │ │ ├── data-card.tsx │ │ │ ├── dialog.tsx │ │ │ ├── draggable-card.tsx │ │ │ ├── dropdown-menu.tsx │ │ │ ├── grouped-card.tsx │ │ │ ├── index.ts │ │ │ ├── input.tsx │ │ │ ├── inspector-dialog.tsx │ │ │ ├── label.tsx │ │ │ ├── pill-navigation.tsx │ │ │ ├── pill.tsx │ │ │ ├── radio-group.tsx │ │ │ ├── select.tsx │ │ │ ├── selectable-card.tsx │ │ │ ├── styles.ts │ │ │ ├── switch.tsx │ │ │ ├── tabs.tsx │ │ │ ├── toast.tsx │ │ │ ├── toggle-group.tsx │ │ │ └── tooltip.tsx │ │ ├── hooks/ │ │ │ ├── useBugReport.ts │ │ │ ├── useMigrationStatus.ts │ │ │ └── useStaggeredEntrance.ts │ │ ├── index.css │ │ ├── index.tsx │ │ ├── lib/ │ │ │ └── utils.ts │ │ ├── pages/ │ │ │ ├── AgentWorkOrderDetailPage.tsx │ │ │ ├── AgentWorkOrdersPage.tsx │ │ │ ├── KnowledgeBasePage.tsx │ │ │ ├── MCPPage.tsx │ │ │ ├── OnboardingPage.tsx │ │ │ ├── ProjectPage.tsx │ │ │ ├── SettingsPage.tsx │ │ │ └── StyleGuidePage.tsx │ │ ├── services/ │ │ │ ├── agentChatService.ts │ │ │ ├── bugReportService.ts │ │ │ ├── credentialsService.ts │ │ │ ├── ollamaService.ts │ │ │ ├── openrouterService.ts │ │ │ └── serverHealthService.ts │ │ ├── styles/ │ │ │ ├── card-animations.css │ │ │ ├── luminous-button.css │ │ │ └── toggle.css │ │ └── utils/ │ │ └── onboarding.ts │ ├── tailwind.config.js │ ├── tests/ │ │ ├── README.md │ │ ├── integration/ │ │ │ ├── knowledge/ │ │ │ │ ├── knowledge-api.test.ts │ │ │ │ └── progress-api.test.ts │ │ │ └── setup.ts │ │ ├── manual/ │ │ │ └── test-knowledge-api.ts │ │ └── setup.ts │ ├── tsconfig.json │ ├── tsconfig.node.json │ ├── tsconfig.prod.json │ ├── vite.config.ts │ ├── vitest.config.ts │ └── vitest.integration.config.ts ├── check-env.js ├── docker-compose.yml ├── migration/ │ ├── 0.1.0/ │ │ ├── 001_add_source_url_display_name.sql │ │ ├── 002_add_hybrid_search_tsvector.sql │ │ ├── 003_ollama_add_columns.sql │ │ ├── 004_ollama_migrate_data.sql │ │ ├── 005_ollama_create_functions.sql │ │ ├── 006_ollama_create_indexes_optional.sql │ │ ├── 007_add_priority_column_to_tasks.sql │ │ ├── 008_add_migration_tracking.sql │ │ ├── 009_add_cascade_delete_constraints.sql │ │ ├── 010_add_provider_placeholders.sql │ │ ├── 011_add_page_metadata_table.sql │ │ └── DB_UPGRADE_INSTRUCTIONS.md │ ├── AGENT_WORK_ORDERS.md │ ├── RESET_DB.sql │ ├── agent_work_orders_repositories.sql │ ├── agent_work_orders_state.sql │ ├── backup_database.sql │ └── complete_setup.sql └── python/ ├── .claude/ │ └── commands/ │ └── agent-work-orders/ │ ├── commit.md │ ├── create-branch.md │ ├── create-pr.md │ ├── execute.md │ ├── noqa.md │ ├── planning.md │ ├── prime.md │ ├── prp-review.md │ └── start-server.md ├── .dockerignore ├── .gitignore ├── Dockerfile.agent-work-orders ├── Dockerfile.agents ├── Dockerfile.mcp ├── Dockerfile.server ├── pyproject.toml ├── pyrightconfig.json ├── pytest.ini ├── src/ │ ├── __init__.py │ ├── agent_work_orders/ │ │ ├── CLAUDE.md │ │ ├── README.md │ │ ├── __init__.py │ │ ├── agent_executor/ │ │ │ ├── __init__.py │ │ │ └── agent_cli_executor.py │ │ ├── api/ │ │ │ ├── __init__.py │ │ │ ├── routes.py │ │ │ └── sse_streams.py │ │ ├── command_loader/ │ │ │ ├── __init__.py │ │ │ └── claude_command_loader.py │ │ ├── config.py │ │ ├── database/ │ │ │ ├── __init__.py │ │ │ └── client.py │ │ ├── github_integration/ │ │ │ ├── __init__.py │ │ │ └── github_client.py │ │ ├── main.py │ │ ├── models.py │ │ ├── sandbox_manager/ │ │ │ ├── __init__.py │ │ │ ├── git_branch_sandbox.py │ │ │ ├── git_worktree_sandbox.py │ │ │ ├── sandbox_factory.py │ │ │ └── sandbox_protocol.py │ │ ├── server.py │ │ ├── state_manager/ │ │ │ ├── __init__.py │ │ │ ├── file_state_repository.py │ │ │ ├── repository_config_repository.py │ │ │ ├── repository_factory.py │ │ │ ├── supabase_repository.py │ │ │ └── work_order_repository.py │ │ ├── utils/ │ │ │ ├── __init__.py │ │ │ ├── git_operations.py │ │ │ ├── id_generator.py │ │ │ ├── log_buffer.py │ │ │ ├── port_allocation.py │ │ │ ├── state_reconciliation.py │ │ │ ├── structured_logger.py │ │ │ └── worktree_operations.py │ │ └── workflow_engine/ │ │ ├── __init__.py │ │ ├── agent_names.py │ │ ├── workflow_operations.py │ │ └── workflow_orchestrator.py │ ├── agents/ │ │ ├── __init__.py │ │ ├── base_agent.py │ │ ├── document_agent.py │ │ ├── mcp_client.py │ │ ├── rag_agent.py │ │ └── server.py │ ├── mcp_server/ │ │ ├── __init__.py │ │ ├── features/ │ │ │ ├── documents/ │ │ │ │ ├── __init__.py │ │ │ │ ├── document_tools.py │ │ │ │ └── version_tools.py │ │ │ ├── feature_tools.py │ │ │ ├── projects/ │ │ │ │ ├── __init__.py │ │ │ │ └── project_tools.py │ │ │ ├── rag/ │ │ │ │ ├── __init__.py │ │ │ │ └── rag_tools.py │ │ │ └── tasks/ │ │ │ ├── __init__.py │ │ │ └── task_tools.py │ │ ├── mcp_server.py │ │ ├── models.py │ │ └── utils/ │ │ ├── __init__.py │ │ ├── error_handling.py │ │ ├── http_client.py │ │ └── timeout_config.py │ └── server/ │ ├── __init__.py │ ├── api_routes/ │ │ ├── __init__.py │ │ ├── agent_chat_api.py │ │ ├── agent_work_orders_proxy.py │ │ ├── bug_report_api.py │ │ ├── internal_api.py │ │ ├── knowledge_api.py │ │ ├── mcp_api.py │ │ ├── migration_api.py │ │ ├── ollama_api.py │ │ ├── openrouter_api.py │ │ ├── pages_api.py │ │ ├── progress_api.py │ │ ├── projects_api.py │ │ ├── providers_api.py │ │ ├── settings_api.py │ │ └── version_api.py │ ├── config/ │ │ ├── __init__.py │ │ ├── config.py │ │ ├── logfire_config.py │ │ ├── service_discovery.py │ │ └── version.py │ ├── main.py │ ├── middleware/ │ │ └── logging_middleware.py │ ├── models/ │ │ └── progress_models.py │ ├── services/ │ │ ├── __init__.py │ │ ├── client_manager.py │ │ ├── crawler_manager.py │ │ ├── crawling/ │ │ │ ├── __init__.py │ │ │ ├── code_extraction_service.py │ │ │ ├── crawling_service.py │ │ │ ├── discovery_service.py │ │ │ ├── document_storage_operations.py │ │ │ ├── helpers/ │ │ │ │ ├── __init__.py │ │ │ │ ├── llms_full_parser.py │ │ │ │ ├── site_config.py │ │ │ │ └── url_handler.py │ │ │ ├── page_storage_operations.py │ │ │ ├── progress_mapper.py │ │ │ └── strategies/ │ │ │ ├── __init__.py │ │ │ ├── batch.py │ │ │ ├── recursive.py │ │ │ ├── single_page.py │ │ │ └── sitemap.py │ │ ├── credential_service.py │ │ ├── embeddings/ │ │ │ ├── __init__.py │ │ │ ├── contextual_embedding_service.py │ │ │ ├── embedding_exceptions.py │ │ │ ├── embedding_service.py │ │ │ ├── multi_dimensional_embedding_service.py │ │ │ └── provider_error_adapters.py │ │ ├── knowledge/ │ │ │ ├── __init__.py │ │ │ ├── database_metrics_service.py │ │ │ ├── knowledge_item_service.py │ │ │ └── knowledge_summary_service.py │ │ ├── llm_provider_service.py │ │ ├── mcp_service_client.py │ │ ├── mcp_session_manager.py │ │ ├── migration_service.py │ │ ├── ollama/ │ │ │ ├── __init__.py │ │ │ ├── embedding_router.py │ │ │ └── model_discovery_service.py │ │ ├── openrouter_discovery_service.py │ │ ├── projects/ │ │ │ ├── __init__.py │ │ │ ├── document_service.py │ │ │ ├── project_creation_service.py │ │ │ ├── project_service.py │ │ │ ├── source_linking_service.py │ │ │ ├── task_service.py │ │ │ └── versioning_service.py │ │ ├── prompt_service.py │ │ ├── provider_discovery_service.py │ │ ├── search/ │ │ │ ├── __init__.py │ │ │ ├── agentic_rag_strategy.py │ │ │ ├── base_search_strategy.py │ │ │ ├── hybrid_search_strategy.py │ │ │ ├── keyword_extractor.py │ │ │ ├── rag_service.py │ │ │ └── reranking_strategy.py │ │ ├── source_management_service.py │ │ ├── storage/ │ │ │ ├── __init__.py │ │ │ ├── base_storage_service.py │ │ │ ├── code_storage_service.py │ │ │ ├── document_storage_service.py │ │ │ └── storage_services.py │ │ ├── threading_service.py │ │ └── version_service.py │ └── utils/ │ ├── __init__.py │ ├── document_processing.py │ ├── etag_utils.py │ ├── progress/ │ │ ├── __init__.py │ │ └── progress_tracker.py │ └── semantic_version.py └── tests/ ├── __init__.py ├── agent_work_orders/ │ ├── conftest.py │ ├── pytest.ini │ ├── test_agent_executor.py │ ├── test_api.py │ ├── test_command_loader.py │ ├── test_config.py │ ├── test_github_integration.py │ ├── test_id_generator.py │ ├── test_log_buffer.py │ ├── test_models.py │ ├── test_port_allocation.py │ ├── test_repository_config_repository.py │ ├── test_sandbox_manager.py │ ├── test_server.py │ ├── test_sse_streams.py │ ├── test_state_manager.py │ ├── test_workflow_operations.py │ └── test_workflow_orchestrator.py ├── conftest.py ├── mcp_server/ │ ├── __init__.py │ ├── features/ │ │ ├── __init__.py │ │ ├── documents/ │ │ │ ├── __init__.py │ │ │ ├── test_document_tools.py │ │ │ └── test_version_tools.py │ │ ├── projects/ │ │ │ ├── __init__.py │ │ │ └── test_project_tools.py │ │ ├── tasks/ │ │ │ ├── __init__.py │ │ │ └── test_task_tools.py │ │ └── test_feature_tools.py │ └── utils/ │ ├── __init__.py │ ├── test_error_handling.py │ └── test_timeout_config.py ├── progress_tracking/ │ ├── __init__.py │ ├── integration/ │ │ ├── __init__.py │ │ ├── test_crawl_orchestration_progress.py │ │ └── test_document_storage_progress.py │ ├── test_batch_progress_bug.py │ ├── test_progress_api.py │ ├── test_progress_mapper.py │ ├── test_progress_models.py │ ├── test_progress_tracker.py │ └── utils/ │ ├── __init__.py │ └── test_helpers.py ├── server/ │ ├── __init__.py │ ├── api_routes/ │ │ ├── __init__.py │ │ ├── test_bug_report_api.py │ │ ├── test_mcp_api.py │ │ ├── test_migration_api.py │ │ ├── test_projects_api_polling.py │ │ └── test_version_api.py │ ├── services/ │ │ ├── __init__.py │ │ ├── projects/ │ │ │ └── __init__.py │ │ ├── test_llms_full_parser.py │ │ ├── test_migration_service.py │ │ └── test_version_service.py │ └── utils/ │ ├── __init__.py │ └── test_etag_utils.py ├── test_api_essentials.py ├── test_async_credential_service.py ├── test_async_embedding_service.py ├── test_async_llm_provider_service.py ├── test_async_source_summary.py ├── test_business_logic.py ├── test_code_extraction_source_id.py ├── test_crawl_orchestration_isolated.py ├── test_crawling_service_subdomain.py ├── test_discovery_service.py ├── test_document_storage_metrics.py ├── test_embedding_service_no_zeros.py ├── test_keyword_extraction.py ├── test_knowledge_api_integration.py ├── test_knowledge_api_pagination.py ├── test_llms_txt_link_following.py ├── test_openrouter_discovery.py ├── test_port_configuration.py ├── test_progress_api.py ├── test_rag_simple.py ├── test_rag_strategies.py ├── test_service_integration.py ├── test_settings_api.py ├── test_source_id_refactor.py ├── test_source_race_condition.py ├── test_source_url_shadowing.py ├── test_supabase_validation.py ├── test_task_counts.py ├── test_token_optimization.py ├── test_token_optimization_integration.py ├── test_url_canonicalization.py └── test_url_handler.py ================================================ FILE CONTENTS ================================================ ================================================ FILE: .claude/agents/codebase-analyst.md ================================================ --- name: "codebase-analyst" description: "Use proactively to find codebase patterns, coding style and team standards. Specialized agent for deep codebase pattern analysis and convention discovery" model: "sonnet" --- You are a specialized codebase analysis agent focused on discovering patterns, conventions, and implementation approaches. ## Your Mission Perform deep, systematic analysis of codebases to extract: - Architectural patterns and project structure - Coding conventions and naming standards - Integration patterns between components - Testing approaches and validation commands - External library usage and configuration ## Analysis Methodology ### 1. Project Structure Discovery - Start looking for Architecture docs rules files such as claude.md, agents.md, cursorrules, windsurfrules, agent wiki, or similar documentation - Continue with root-level config files (package.json, pyproject.toml, go.mod, etc.) - Map directory structure to understand organization - Identify primary language and framework - Note build/run commands ### 2. Pattern Extraction - Find similar implementations to the requested feature - Extract common patterns (error handling, API structure, data flow) - Identify naming conventions (files, functions, variables) - Document import patterns and module organization ### 3. Integration Analysis - How are new features typically added? - Where do routes/endpoints get registered? - How are services/components wired together? - What's the typical file creation pattern? ### 4. Testing Patterns - What test framework is used? - How are tests structured? - What are common test patterns? - Extract validation command examples ### 5. Documentation Discovery - Check for README files - Find API documentation - Look for inline code comments with patterns - Check PRPs/ai_docs/ for curated documentation ## Output Format Provide findings in structured format: ```yaml project: language: [detected language] framework: [main framework] structure: [brief description] patterns: naming: files: [pattern description] functions: [pattern description] classes: [pattern description] architecture: services: [how services are structured] models: [data model patterns] api: [API patterns] testing: framework: [test framework] structure: [test file organization] commands: [common test commands] similar_implementations: - file: [path] relevance: [why relevant] pattern: [what to learn from it] libraries: - name: [library] usage: [how it's used] patterns: [integration patterns] validation_commands: syntax: [linting/formatting commands] test: [test commands] run: [run/serve commands] ``` ## Key Principles - Be specific - point to exact files and line numbers - Extract executable commands, not abstract descriptions - Focus on patterns that repeat across the codebase - Note both good patterns to follow and anti-patterns to avoid - Prioritize relevance to the requested feature/story ## Search Strategy 1. Start broad (project structure) then narrow (specific patterns) 2. Use parallel searches when investigating multiple aspects 3. Follow references - if a file imports something, investigate it 4. Look for "similar" not "same" - patterns often repeat with variations Remember: Your analysis directly determines implementation success. Be thorough, specific, and actionable. ================================================ FILE: .claude/agents/library-researcher.md ================================================ --- name: "library-researcher" description: "Use proactively to research external libraries and fetch implementation-critical documentation" model: "sonnet" --- You are a specialized library research agent focused on gathering implementation-critical documentation. ## Your Mission Research external libraries and APIs to provide: - Specific implementation examples - API method signatures and patterns - Common pitfalls and best practices - Version-specific considerations ## Research Strategy ### 1. Official Documentation - Start with Archon MCP tools and check if we have relevant docs in the database - Use the RAG tools to search for relevant documentation, use specific keywords and context in your queries - Use websearch and webfetch to search official docs (check package registry for links) - Find quickstart guides and API references - Identify code examples specific to the use case - Note version-specific features or breaking changes ### 2. Implementation Examples - Search GitHub for real-world usage - Find Stack Overflow solutions for common patterns - Look for blog posts with practical examples - Check the library's test files for usage patterns ### 3. Integration Patterns - How do others integrate this library? - What are common configuration patterns? - What helper utilities are typically created? - What are typical error handling patterns? ### 4. Known Issues - Check library's GitHub issues for gotchas - Look for migration guides indicating breaking changes - Find performance considerations - Note security best practices ## Output Format Structure findings for immediate use: ```yaml library: [library name] version: [version in use] documentation: quickstart: [URL with section anchor] api_reference: [specific method docs URL] examples: [example code URL] key_patterns: initialization: | [code example] common_usage: | [code example] error_handling: | [code example] gotchas: - issue: [description] solution: [how to handle] best_practices: - [specific recommendation] save_to_ai_docs: [yes/no - if complex enough to warrant local documentation] ``` ## Documentation Curation When documentation is complex or critical: 1. Create condensed version in PRPs/ai_docs/{library}\_patterns.md 2. Focus on implementation-relevant sections 3. Include working code examples 4. Add project-specific integration notes ## Search Queries Effective search patterns: - "{library} {feature} example" - "{library} TypeError site:stackoverflow.com" - "{library} best practices {language}" - "github {library} {feature} language:{language}" ## Key Principles - Prefer official docs but verify with real implementations - Focus on the specific features needed for the story - Provide executable code examples, not abstract descriptions - Note version differences if relevant - Save complex findings to ai_docs for future reference Remember: Good library research prevents implementation blockers and reduces debugging time. ================================================ FILE: .claude/commands/agent-work-orders/commit.md ================================================ # Create Git Commit Create an atomic git commit with a properly formatted commit message following best practices for the uncommited changes or these specific files if specified. Specific files (skip if not specified): - File 1: $1 - File 2: $2 - File 3: $3 - File 4: $4 - File 5: $5 ## Instructions **Commit Message Format:** - Use conventional commits: `: ` - Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore` - Present tense (e.g., "add", "fix", "update", not "added", "fixed", "updated") - 50 characters or less for the subject line - Lowercase subject line - No period at the end - Be specific and descriptive **Examples:** - `feat: add web search tool with structured logging` - `fix: resolve type errors in middleware` - `test: add unit tests for config module` - `docs: update CLAUDE.md with testing guidelines` - `refactor: simplify logging configuration` - `chore: update dependencies` **Atomic Commits:** - One logical change per commit - If you've made multiple unrelated changes, consider splitting into separate commits - Commit should be self-contained and not break the build **IMPORTANT** - NEVER mention claude code, anthropic, co authored by or anything similar in the commit messages ## Run 1. Review changes: `git diff HEAD` 2. Check status: `git status` 3. Stage changes: `git add -A` 4. Create commit: `git commit -m ": "` ## Report - Output the commit message used - Confirm commit was successful with commit hash - List files that were committed ================================================ FILE: .claude/commands/agent-work-orders/execute.md ================================================ # Execute PRP Plan Implement a feature plan from the PRPs directory by following its Step by Step Tasks section. ## Variables Plan file: $ARGUMENTS ## Instructions - Read the entire plan file carefully - Execute **every step** in the "Step by Step Tasks" section in order, top to bottom - Follow the "Testing Strategy" to create proper unit and integration tests - Complete all "Validation Commands" at the end - Ensure all linters pass and all tests pass before finishing - Follow CLAUDE.md guidelines for type safety, logging, and docstrings ## When done - Move the PRP file to the completed directory in PRPs/features/completed ## Report - Summarize completed work in a concise bullet point list - Show files and lines changed: `git diff --stat` - Confirm all validation commands passed - Note any deviations from the plan (if any) ================================================ FILE: .claude/commands/agent-work-orders/noqa.md ================================================ # NOQA Analysis and Resolution Find all noqa/type:ignore comments in the codebase, investigate why they exist, and provide recommendations for resolution or justification. ## Instructions **Step 1: Find all NOQA comments** - Use Grep tool to find all noqa comments: pattern `noqa|type:\s*ignore` - Use output_mode "content" with line numbers (-n flag) - Search across all Python files (type: "py") - Document total count of noqa comments found **Step 2: For EACH noqa comment (repeat this process):** - Read the file containing the noqa comment with sufficient context (at least 10 lines before and after) - Identify the specific linting rule or type error being suppressed - Understand the code's purpose and why the suppression was added - Investigate if the suppression is still necessary or can be resolved **Step 3: Investigation checklist for each noqa:** - What specific error/warning is being suppressed? (e.g., `type: ignore[arg-type]`, `noqa: F401`) - Why was the suppression necessary? (legacy code, false positive, legitimate limitation, technical debt) - Can the underlying issue be fixed? (refactor code, update types, improve imports) - What would it take to remove the suppression? (effort estimate, breaking changes, architectural changes) - Is the suppression justified long-term? (external library limitation, Python limitation, intentional design) **Step 4: Research solutions:** - Check if newer versions of tools (mypy, ruff) handle the case better - Look for alternative code patterns that avoid the suppression - Consider if type stubs or Protocol definitions could help - Evaluate if refactoring would be worthwhile ## Report Format Create a markdown report file (create the reports directory if not created yet): `PRPs/reports/noqa-analysis-{YYYY-MM-DD}.md` Use this structure for the report: ````markdown # NOQA Analysis Report **Generated:** {date} **Total NOQA comments found:** {count} --- ## Summary - Total suppressions: {count} - Can be removed: {count} - Should remain: {count} - Requires investigation: {count} --- ## Detailed Analysis ### 1. {File path}:{line number} **Location:** `{file_path}:{line_number}` **Suppression:** `{noqa comment or type: ignore}` **Code context:** ```python {relevant code snippet} ``` ```` **Why it exists:** {explanation of why the suppression was added} **Options to resolve:** 1. {Option 1: description} - Effort: {Low/Medium/High} - Breaking: {Yes/No} - Impact: {description} 2. {Option 2: description} - Effort: {Low/Medium/High} - Breaking: {Yes/No} - Impact: {description} **Tradeoffs:** - {Tradeoff 1} - {Tradeoff 2} **Recommendation:** {Remove | Keep | Refactor} {Justification for recommendation} --- {Repeat for each noqa comment} ```` ## Example Analysis Entry ```markdown ### 1. src/shared/config.py:45 **Location:** `src/shared/config.py:45` **Suppression:** `# type: ignore[assignment]` **Code context:** ```python @property def openai_api_key(self) -> str: key = os.getenv("OPENAI_API_KEY") if not key: raise ValueError("OPENAI_API_KEY not set") return key # type: ignore[assignment] ```` **Why it exists:** MyPy cannot infer that the ValueError prevents None from being returned, so it thinks the return type could be `str | None`. **Options to resolve:** 1. Use assert to help mypy narrow the type - Effort: Low - Breaking: No - Impact: Cleaner code, removes suppression 2. Add explicit cast with typing.cast() - Effort: Low - Breaking: No - Impact: More verbose but type-safe 3. Refactor to use separate validation method - Effort: Medium - Breaking: No - Impact: Better separation of concerns **Tradeoffs:** - Option 1 (assert) is cleanest but asserts can be disabled with -O flag - Option 2 (cast) is most explicit but adds import and verbosity - Option 3 is most robust but requires more refactoring **Recommendation:** Remove (use Option 1) Replace the type:ignore with an assert statement after the if check. This helps mypy understand the control flow while maintaining runtime safety. The assert will never fail in practice since the ValueError is raised first. **Implementation:** ```python @property def openai_api_key(self) -> str: key = os.getenv("OPENAI_API_KEY") if not key: raise ValueError("OPENAI_API_KEY not set") assert key is not None # Help mypy understand control flow return key ``` ``` ## Report After completing the analysis: - Output the path to the generated report file - Summarize findings: - Total suppressions found - How many can be removed immediately (low effort) - How many should remain (justified) - How many need deeper investigation or refactoring - Highlight any quick wins (suppressions that can be removed with minimal effort) ``` ================================================ FILE: .claude/commands/agent-work-orders/planning.md ================================================ # Feature Planning Create a new plan to implement the `PRP` using the exact specified markdown `PRP Format`. Follow the `Instructions` to create the plan use the `Relevant Files` to focus on the right files. ## Variables FEATURE $1 $2 ## Instructions - IMPORTANT: You're writing a plan to implement a net new feature based on the `Feature` that will add value to the application. - IMPORTANT: The `Feature` describes the feature that will be implemented but remember we're not implementing a new feature, we're creating the plan that will be used to implement the feature based on the `PRP Format` below. - Create the plan in the `PRPs/features/` directory with filename: `{descriptive-name}.md` - Replace `{descriptive-name}` with a short, descriptive name based on the feature (e.g., "add-auth-system", "implement-search", "create-dashboard") - Use the `PRP Format` below to create the plan. - Deeply research the codebase to understand existing patterns, architecture, and conventions before planning the feature. - If no patterns are established or are unclear ask the user for clarifications while providing best recommendations and options - IMPORTANT: Replace every in the `PRP Format` with the requested value. Add as much detail as needed to implement the feature successfully. - Use your reasoning model: THINK HARD about the feature requirements, design, and implementation approach. - Follow existing patterns and conventions in the codebase. Don't reinvent the wheel. - Design for extensibility and maintainability. - Deeply do web research to understand the latest trends and technologies in the field. - Figure out latest best practices and library documentation. - Include links to relevant resources and documentation with anchor tags for easy navigation. - If you need a new library, use `uv add ` and report it in the `Notes` section. - Read `CLAUDE.md` for project principles, logging rules, testing requirements, and docstring style. - All code MUST have type annotations (strict mypy enforcement). - Use Google-style docstrings for all functions, classes, and modules. - Every new file in `src/` MUST have a corresponding test file in `tests/`. - Respect requested files in the `Relevant Files` section. ## Relevant Files Focus on the following files and vertical slice structure: **Core Files:** - `CLAUDE.md` - Project instructions, logging rules, testing requirements, docstring style app/backend core files app/frontend core files ## PRP Format ```md # Feature: ## Feature Description ## User Story As a I want to So that ## Problem Statement ## Solution Statement ## Relevant Files Use these files to implement the feature: ## Relevant research docstring Use these documentation files and links to help with understanding the technology to use: - [Documentation Link 1](https://example.com/doc1) - [Anchor tag] - [Short summary] - [Documentation Link 2](https://example.com/doc2) - [Anchor tag] - [Short summary] ## Implementation Plan ### Phase 1: Foundation ### Phase 2: Core Implementation ### Phase 3: Integration ## Step by Step Tasks IMPORTANT: Execute every step in order, top to bottom. /test_.py` - Add integration test in `tests/integration/` if needed> ## Testing Strategy See `CLAUDE.md` for complete testing requirements. Every file in `src/` must have a corresponding test file in `tests/`. ### Unit Tests ### Integration Tests ### Edge Cases ## Acceptance Criteria ## Validation Commands Execute every command to validate the feature works correctly with zero regressions. **Required validation commands:** - `uv run ruff check src/` - Lint check must pass - `uv run mypy src/` - Type check must pass - `uv run pytest tests/ -v` - All tests must pass with zero regressions **Run server and test core endpoints:** - Start server: @.claude/start-server - Test endpoints with curl (at minimum: health check, main functionality) - Verify structured logs show proper correlation IDs and context - Stop server after validation ## Notes ``` ## Feature Extract the feature details from the `issue_json` variable (parse the JSON and use the title and body fields). ## Report - Summarize the work you've just done in a concise bullet point list. - Include the full path to the plan file you created (e.g., `PRPs/features/add-auth-system.md`) ================================================ FILE: .claude/commands/agent-work-orders/prime.md ================================================ # Prime Execute the following sections to understand the codebase before starting new work, then summarize your understanding. ## Run - List all tracked files: `git ls-files` - Show project structure: `tree -I '.venv|__pycache__|*.pyc|.pytest_cache|.mypy_cache|.ruff_cache' -L 3` ## Read - `CLAUDE.md` - Core project instructions, principles, logging rules, testing requirements - `python/src/agent_work_orders` - Project overview and setup (if exists) - Identify core files in the agent work orders directory to understand what we are woerking on and its intent ## Report Provide a concise summary of: 1. **Project Purpose**: What this application does 2. **Architecture**: Key patterns (vertical slice, FastAPI + Pydantic AI) 3. **Core Principles**: TYPE SAFETY, KISS, YAGNI 4. **Tech Stack**: Main dependencies and tools 5. **Key Requirements**: Logging, testing, type annotations 6. **Current State**: What's implemented Keep the summary brief (5-10 bullet points) and focused on what you need to know to contribute effectively. ================================================ FILE: .claude/commands/agent-work-orders/prp-review.md ================================================ # Code Review Review implemented work against a PRP specification to ensure code quality, correctness, and adherence to project standards. ## Variables Plan file: $ARGUMENTS (e.g., `PRPs/features/add-web-search.md`) ## Instructions **Understand the Changes:** - Check current branch: `git branch` - Review changes: `git diff origin/main` (or `git diff HEAD` if not on a branch) - Read the PRP plan file to understand requirements **Code Quality Review:** - **Type Safety**: Verify all functions have type annotations, mypy passes - **Logging**: Check structured logging is used correctly (event names, context, exception handling) - **Docstrings**: Ensure Google-style docstrings on all functions/classes - **Testing**: Verify unit tests exist for all new files, integration tests if needed - **Architecture**: Confirm vertical slice structure is followed - **CLAUDE.md Compliance**: Check adherence to core principles (KISS, YAGNI, TYPE SAFETY) **Validation Ruff for BE and Biome for FE:** - Run linters: `uv run ruff check src/ && uv run mypy src/` - Run tests: `uv run pytest tests/ -v` - Start server and test endpoints with curl (if applicable) - Verify structured logs show proper correlation IDs and context **Issue Severity:** - `blocker` - Must fix before merge (breaks build, missing tests, type errors, security issues) - `major` - Should fix (missing logging, incomplete docstrings, poor patterns) - `minor` - Nice to have (style improvements, optimization opportunities) ## Report Return ONLY valid JSON (no markdown, no explanations) save to [report-#.json] in prps/reports directory create the directory if it doesn't exist. Output will be parsed with JSON.parse(). ### Output Structure ```json { "success": "boolean - true if NO BLOCKER issues, false if BLOCKER issues exist", "review_summary": "string - 2-4 sentences: what was built, does it match spec, quality assessment", "review_issues": [ { "issue_number": "number - issue index", "file_path": "string - file with the issue (if applicable)", "issue_description": "string - what's wrong", "issue_resolution": "string - how to fix it", "severity": "string - blocker|major|minor" } ], "validation_results": { "linting_passed": "boolean", "type_checking_passed": "boolean", "tests_passed": "boolean", "api_endpoints_tested": "boolean - true if endpoints were tested with curl" } } ``` ## Example Success Review ```json { "success": true, "review_summary": "The web search tool has been implemented with proper type annotations, structured logging, and comprehensive tests. The implementation follows the vertical slice architecture and matches all spec requirements. Code quality is high with proper error handling and documentation.", "review_issues": [ { "issue_number": 1, "file_path": "src/tools/web_search/tool.py", "issue_description": "Missing debug log for API response", "issue_resolution": "Add logger.debug with response metadata", "severity": "minor" } ], "validation_results": { "linting_passed": true, "type_checking_passed": true, "tests_passed": true, "api_endpoints_tested": true } } ``` ================================================ FILE: .claude/commands/agent-work-orders/start-server.md ================================================ # Start Servers Start both the FastAPI backend and React frontend development servers with hot reload. ## Run ### Run in the background with bash tool - Ensure you are in the right PWD - Use the Bash tool to run the servers in the background so you can read the shell outputs - IMPORTANT: run `git ls-files` first so you know where directories are located before you start ### Backend Server (FastAPI) - Navigate to backend: `cd app/backend` - Start server in background: `uv sync && uv run python run_api.py` - Wait 2-3 seconds for startup - Test health endpoint: `curl http://localhost:8000/health` - Test products endpoint: `curl http://localhost:8000/api/products` ### Frontend Server (Bun + React) - Navigate to frontend: `cd ../app/frontend` - Start server in background: `bun install && bun dev` - Wait 2-3 seconds for startup - Frontend should be accessible at `http://localhost:3000` ## Report - Confirm backend is running on `http://localhost:8000` - Confirm frontend is running on `http://localhost:3000` - Show the health check response from backend - Mention: "Backend logs will show structured JSON logging for all requests" ================================================ FILE: .claude/commands/archon/archon-alpha-review.md ================================================ --- description: Perform comprehensive code review for Archon V2 Beta, this command will save a report to `code-review.md`. argument-hint: allowed-tools: Bash(*), Read, Grep, LS, Write thinking: auto --- # Code Review for Archon V2 Beta **Review scope**: $ARGUMENTS I'll perform a comprehensive code review and generate a report saved to the root of this directory as `code-review[n].md`. check if other reviews exist before you create the file and increment n as needed. ## Context You're reviewing code for Archon V2 Beta, which uses: - **Frontend**: React + TypeScript + Vite + TailwindCSS - **Backend**: Python 3.12+ with FastAPI, PydanticAI, Supabase - **Testing**: Vitest for frontend, pytest for backend - **Code Quality**: ruff, mypy, ESLint ## What to Review Determine what needs reviewing: - If no arguments: Review staged changes (`git diff --staged`) - If PR number: Review pull request (`gh pr view`) - If branch name: Compare with main (`git diff main...branch`) - If file path: Review specific files - If directory: Review all changes in that area ## Review Focus ### CRITICAL: Beta Error Handling Philosophy **Following CLAUDE.md principles - We want DETAILED ERRORS, not graceful failures!** #### Where Errors MUST Bubble Up (Fail Fast & Loud): - **Service initialization** - If credentials, database, or MCP fails to start, CRASH - **Configuration errors** - Missing env vars, invalid settings should STOP the system - **Database connection failures** - Don't hide connection issues, expose them - **Authentication failures** - Security errors must be visible - **Data corruption** - Never silently accept bad data - **Type validation errors** - Pydantic should raise, not coerce #### Where to Complete but Log Clearly: - **Background tasks** (crawling, embeddings) - Complete the job, log failures per item - **Batch operations** - Process what you can, report what failed with details - **WebSocket events** - Don't crash on single event failure, log and continue - **Optional features** - If projects/tasks disabled, log and skip - **External API calls** - Retry with exponential backoff, then fail with clear message ### Python Code Quality Look for: - **Type hints** on all functions and proper use of Python 3.12+ features - **Pydantic v2 patterns** (ConfigDict, model_dump, field_validator) - **Error handling following beta principles**: ```python # BAD - Silent failure try: result = risky_operation() except Exception: return None # GOOD - Detailed error with context try: result = risky_operation() except SpecificError as e: logger.error(f"Operation failed at step X: {e}", exc_info=True) raise # Let it bubble up! ``` - **No print statements** - should use logging instead - **Detailed error messages** with context about what was being attempted - **Stack traces preserved** with `exc_info=True` in logging - **Async/await** used correctly with proper exception propagation ### TypeScript/React Quality Look for: - **TypeScript types** properly defined, avoid `any` - **React error boundaries** for component failures - **API error handling** that shows actual error messages: ```typescript // BAD - Generic error catch (error) { setError("Something went wrong"); } // GOOD - Specific error with details catch (error) { console.error("API call failed:", error); setError(`Failed to load data: ${error.message}`); } ``` - **Component structure** following existing patterns - **Console.error** for debugging, not hidden errors ### Security Considerations Check for: - Input validation that FAILS LOUDLY on bad input - SQL injection vulnerabilities - No hardcoded secrets or API keys - Authentication that clearly reports why it failed - CORS configuration with explicit error messages ### Architecture & Patterns Ensure: - Services fail fast on initialization errors - Routes return detailed error responses with status codes - Database operations include transaction details in errors - Socket.IO disconnections are logged with reasons - Service dependencies checked at startup, not runtime ### Testing Verify: - Tests check for specific error messages, not just "throws" - Error paths are tested with expected error details - No catch-all exception handlers hiding issues - Mock failures test error propagation ## Review Process 1. **Understand the changes** - What problem is being solved? 2. **Check functionality** - Does it do what it's supposed to? 3. **Review code quality** - Is it maintainable and follows standards? 4. **Consider performance** - Any N+1 queries or inefficient algorithms? 5. **Verify tests** - Are changes properly tested? 6. **Check documentation** - Are complex parts documented? ## Key Areas to Check **Backend Python files:** - `python/src/server/` - Service layer patterns - `python/src/mcp/` - MCP tool definitions - `python/src/agents/` - AI agent implementations **Frontend TypeScript files:** - `archon-ui-main/src/components/` - React components - `archon-ui-main/src/services/` - API integration - `archon-ui-main/src/hooks/` - Custom hooks **Configuration:** - `docker-compose.yml` - Service configuration - `.env` changes - Security implications - `package.json` / `pyproject.toml` - Dependency changes ## Report Format Generate a `code-review.md` with: ```markdown # Code Review **Date**: [Today's date] **Scope**: [What was reviewed] **Overall Assessment**: [Pass/Needs Work/Critical Issues] ## Summary [Brief overview of changes and general quality] ## Issues Found ### 🔴 Critical (Must Fix) - [Issue description with file:line reference and suggested fix] ### 🟡 Important (Should Fix) - [Issue description with file:line reference] ### 🟢 Suggestions (Consider) - [Minor improvements or style issues] ## What Works Well - [Positive aspects of the code] ## Security Review [Any security concerns or confirmations] ## Performance Considerations [Any performance impacts] ## Test Coverage - Current coverage: [if available] - Missing tests for: [list areas] ## Recommendations [Specific actionable next steps] ``` ## Helpful Commands ```bash # Check what changed git diff --staged git diff main...HEAD gh pr view $PR_NUMBER --json files # Run quality checks cd python && ruff check --fix cd python && mypy src/ cd archon-ui-main && npm run lint # Run tests cd python && uv run pytest cd archon-ui-main && npm test ``` Remember: Focus on impact and maintainability. Good code review helps the team ship better code, not just find problems. Be constructive and specific with feedback. ================================================ FILE: .claude/commands/archon/archon-coderabbit-helper.md ================================================ --- name: Archon CodeRabbit Helper description: Analyze CodeRabbit suggestions, assess validity, and provide actionable options with tradeoffs argument-hint: Paste the CodeRabbit suggestion here --- # CodeRabbit Review Analysis **Review:** $ARGUMENTS ## Instructions Analyze this CodeRabbit suggestion following these steps: ### 1. Deep Analysis - Understand the technical issue being raised - Check if it's a real problem or false positive - Search the codebase for related patterns and context - Consider project phase (early beta) and architecture ### 2. Context Assessment - We're in early beta - prioritize simplicity over perfection - Follow KISS principles and existing codebase patterns - Avoid premature optimization or over-engineering - Consider if this affects user experience or is internal only ### 3. Generate Options Think harder about the problem and potential solutions. Provide 2-5 practical options with clear tradeoffs ## Response Format ### 📋 Issue Summary _[One sentence describing what CodeRabbit found]_ ### ✅ Is this valid? _[YES/NO with brief explanation]_ ### 🎯 Priority for this PR _[HIGH/MEDIUM/LOW/SKIP with reasoning]_ ### 🔧 Options & Tradeoffs **Option 1: [Name]** - What: _[Brief description]_ - Pros: _[Benefits]_ - Cons: _[Drawbacks]_ - Effort: _[Low/Medium/High]_ **Option 2: [Name]** - What: _[Brief description]_ - Pros: _[Benefits]_ - Cons: _[Drawbacks]_ - Effort: _[Low/Medium/High]_ ### 💡 Recommendation _[Your recommended option with 1-2 sentence justification]_ ## User feedback - When you have presented the review to the user you must ask for their feedback on the suggested changes. - Ask the user if they wish to discuss any of the options further - If the user wishes for you to explore further, provide additional options or tradeoffs. - If the user is ready to implement the recommended option right away ================================================ FILE: .claude/commands/archon/archon-onboarding.md ================================================ --- name: archon-onboarding description: | Onboard new developers to the Archon codebase with a comprehensive overview and first contribution guidance. Usage: /archon-onboarding argument-hint: none --- You are helping a new developer get up and running with the Archon V2 Beta project! Your goal is to provide them with a personalized onboarding experience. ## What is Archon? Archon is a centralized knowledge base for AI coding assistants. It enables Claude Code, Cursor, Windsurf, and other AI tools to access your documentation, perform smart searches, and manage tasks - all through a unified interface. Its powered by a **Model Context Protocol (MCP) server** And you can crawl and store knowledge that you can use multiple rag strategies to improve your AI coders performance. ## Quick Architecture Overview This is a **true microservices architecture** with 4 independent services: 1. **Frontend** (port 3737) - React UI for managing knowledge and projects 2. **Server** (port 8181) - Core API handling all business logic 3. **MCP Server** (port 8051) - Lightweight MCP protocol interface 4. **Agents** (port 8052) - AI operations with PydanticAI All services communicate via HTTP only - no shared code, true separation of concerns. ## Getting Started - Your First 30 Minutes ### Prerequisites Check You'll need: - Docker Desktop (running) - Supabase account (free tier works) - OpenAI API key (or Gemini/Ollama) - Git and basic command line knowledge ### Setup First, read the README.md file to understand the setup process, then guide the user through these steps: 1. Clone the repository and set up environment variables 2. Configure Supabase database with migration scripts 3. Start Docker services 4. Configure API keys in the UI 5. Verify everything is working by testing a simple crawl ## Understanding the Codebase ### Decision Time Ask the user to choose their focus area. Present these options clearly and wait for their response: "Which area of the Archon codebase would you like to explore first?" 1. **Frontend (React/TypeScript)** - If you enjoy UI/UX work 2. **Backend API (Python/FastAPI)** - If you like building robust APIs 3. **MCP Tools (Python)** - If you're interested in AI tool protocols 4. **RAG/Search (Python)** - If you enjoy search and ML engineering 5. **Web Crawling (Python)** - If you like data extraction challenges ### Your Onboarding Analysis Based on the user's choice, perform a deep analysis of that area following the instructions below for their specific choice. Then provide them with a structured report. ## Report Structure Your report to the user should include: 1. **Area Overview**: Architecture explanation and how it connects to other services 2. **Key Files Walkthrough**: Purpose of main files and their relationships 3. **Suggested First Contribution**: A specific, small improvement with exact location 4. **Implementation Guide**: Step-by-step instructions to make the change 5. **Testing Instructions**: How to verify their change works correctly **If the user chose Frontend:** - Start with `archon-ui-main/src/pages/KnowledgeBasePage.tsx` - Look at how it uses `services/knowledgeBaseService.ts` - Take a deep dive into the frontend architecture and UI components - Identify a potential issue that the user can easily fix and suggest a solution - Give the user a overview of the frontend and architecture following the report format above **If the user chose Backend API:** - Start with `python/src/server/api_routes/knowledge_api.py` - See how it calls `services/knowledge/knowledge_item_service.py` - Take a deep dive into the FastAPI service architecture and patterns - Identify a potential API improvement that the user can implement - Give the user an overview of the backend architecture and suggest a contribution **If the user chose MCP Tools:** - Start with `python/src/mcp/mcp_server.py` - Look at `modules/rag_module.py` for tool patterns - Take a deep dive into the MCP protocol implementation and available tools - Identify a missing tool or enhancement that would be valuable - Give the user an overview of the MCP architecture and how to add new tools **If the user chose RAG/Search:** - Start with `python/src/server/services/search/vector_search_service.py` - Understand the hybrid search approach - Take a deep dive into the RAG pipeline and search strategies - Identify a search improvement or ranking enhancement opportunity - Give the user an overview of the RAG system and suggest optimizations **If the user chose Web Crawling:** - Start with `python/src/server/services/rag/crawling_service.py` - Look at sitemap detection and parsing logic - Take a deep dive into the crawling architecture and content extraction - Identify a crawling enhancement or new content type support to add - Give the user an overview of the crawling system and parsing strategies ## How to Find Contribution Opportunities When analyzing the user's chosen area, look for: - TODO or FIXME comments in the code - Missing error handling or validation - UI components that could be more user-friendly - API endpoints missing useful filters or data - Areas with minimal or no test coverage - Hardcoded values that should be configurable ## What to Include in Your Report After analyzing their chosen area, provide the user with: 1. Key development patterns they should know: - Beta mindset (break things to improve them) - Error philosophy (fail fast with detailed errors) - Service boundaries (no cross-service imports) - Real-time updates via Socket.IO - Testing approach for their chosen area 2. Specific contribution suggestion with: - Exact file and line numbers to modify - Current behavior vs improved behavior - Step-by-step implementation guide - Testing instructions 3. Common gotchas for their area: - Service-specific pitfalls - Testing requirements - Local vs Docker differences Remember to encourage the user to start small and iterate. This is beta software designed for rapid experimentation. ================================================ FILE: .claude/commands/archon/archon-prime-simple.md ================================================ --- name: prime-simple description: Quick context priming for Archon development - reads essential files and provides project overview argument-hint: none --- ## Prime Context for Archon Development You need to quickly understand the Archon V2 Beta codebase. Follow these steps: ### 1. Read Project Documentation - Read `CLAUDE.md` for development guidelines and patterns - Read `README.md` for project overview and setup ### 2. Understand Project Structure Use `tree -L 2` or explore the directory structure to understand the layout: - `archon-ui-main/` - Frontend React application - `python/` - Backend services (server, MCP, agents) - `docker-compose.yml` - Service orchestration - `migration/` - Database setup scripts ### 3. Read Key Frontend Files Read these essential files in `archon-ui-main/`: - `src/App.tsx` - Main application entry and routing - Make your own decision of how deep to go into other files ### 4. Read Key Backend Files Read these essential files in `python/`: - `src/server/main.py` - FastAPI application setup - Make your own decision of how deep to go into other files ### 5. Review Configuration - `.env.example` - Required environment variables - `docker-compose.yml` - Service definitions and ports - Make your own decision of how deep to go into other files ### 6. Provide Summary After reading these files, explain to the user: 1. **Project Purpose**: One sentence about what Archon does and why it exists 2. **Architecture**: One sentence about the architecture 3. **Key Patterns**: One sentence about key patterns 4. **Tech Stack**: One sentence about tech stack Remember: This is beta software focused on rapid iteration. Prioritize understanding the core functionality ================================================ FILE: .claude/commands/archon/archon-prime.md ================================================ --- name: prime description: | Prime Claude Code with deep context for a specific part of the Archon codebase. Usage: /prime "" "" Examples: /prime "frontend" "Focus on UI components and React" /prime "server" "Focus on FastAPI and backend services" /prime "knowledge" "Focus on RAG and knowledge management" argument-hint: --- You're about to work on the Archon V2 Beta codebase. This is a microservices-based knowledge management system with MCP integration. Here's what you need to know: ## Today's Focus area Today we are focusing on: $ARGUMENTS And pay special attention to: $ARGUMENTS ## Decision Think hard and make an intelligent decision about which key files you need to read and create a todo list. If you discover something you need to look deeper at or imports from files you need context from, append it to the todo list during the priming process. The goal is to get key understandings of the codebase so you are ready to make code changes to that part of the codebase. ## Architecture Overview ### Frontend (port 3737) - React + TypeScript + Vite ``` archon-ui-main/ ├── src/ │ ├── App.tsx # Main app component with routing and providers │ ├── index.tsx # React entry point with theme and settings │ ├── components/ │ │ ├── layouts/ # Layout components (MainLayout, SideNavigation) │ │ ├── knowledge-base/ # Knowledge management UI (crawling, items, search) │ │ ├── project-tasks/ # Project and task management components │ │ ├── prp/ # Product Requirements Prompt viewer components │ │ ├── mcp/ # MCP client management and testing UI │ │ ├── settings/ # Settings panels (API keys, features, RAG config) │ │ └── ui/ # Reusable UI components (buttons, cards, inputs) │ ├── services/ # API client services for backend communication │ │ ├── knowledgeBaseService.ts # Knowledge item CRUD and search operations │ │ ├── projectService.ts # Project and task management API calls │ │ ├── mcpService.ts # MCP server communication and tool execution │ │ └── socketIOService.ts # Real-time WebSocket event handling │ ├── hooks/ # Custom React hooks for state and effects │ ├── contexts/ # React contexts (Settings, Theme, Toast) │ └── pages/ # Main page components for routing ``` ### Backend Server (port 8181) - FastAPI + Socket.IO ``` python/src/server/ ├── main.py # FastAPI app initialization and routing setup ├── socketio_app.py # Socket.IO server configuration and namespaces ├── config/ │ ├── config.py # Environment variables and app configuration │ └── service_discovery.py # Service URL resolution for Docker/local ├── fastapi/ # API route handlers (thin wrappers) │ ├── knowledge_api.py # Knowledge base endpoints (crawl, upload, search) │ ├── projects_api.py # Project and task management endpoints │ ├── mcp_api.py # MCP tool execution and health checks │ └── socketio_handlers.py # Socket.IO event handlers and broadcasts ├── services/ # Business logic layer │ ├── knowledge/ │ │ ├── crawl_orchestration_service.py # Website crawling coordination │ │ ├── knowledge_item_service.py # Knowledge item CRUD operations │ │ └── code_extraction_service.py # Extract code examples from docs │ ├── projects/ │ │ ├── project_service.py # Project management logic │ │ ├── task_service.py # Task lifecycle and status management │ │ └── versioning_service.py # Document version control │ ├── rag/ │ │ └── crawling_service.py # Web crawling implementation │ ├── search/ │ │ └── vector_search_service.py # Semantic search with pgvector │ ├── embeddings/ │ │ └── embedding_service.py # OpenAI embeddings generation │ └── storage/ │ └── document_storage_service.py # Document chunking and storage ``` ### MCP Server (port 8051) - Model Context Protocol ``` python/src/mcp/ ├── mcp_server.py # FastAPI MCP server with SSE support └── modules/ ├── project_module.py # Project and task MCP tools └── rag_module.py # RAG query and search MCP tools ``` ### Agents Service (port 8052) - PydanticAI ``` python/src/agents/ ├── server.py # FastAPI server for agent endpoints ├── base_agent.py # Base agent class with streaming support ├── document_agent.py # Document processing and chunking agent ├── rag_agent.py # RAG search and reranking agent └── mcp_client.py # Client for calling MCP tools ``` ## Key Files to Read for Context ### When working on Frontend Key files to consider: - `archon-ui-main/src/App.tsx` - Main app structure and routing - `archon-ui-main/src/services/knowledgeBaseService.ts` - API call patterns - `archon-ui-main/src/services/socketIOService.ts` - Real-time events ### When working on Backend Key files to consider: - `python/src/server/main.py` - FastAPI app setup - `python/src/server/services/knowledge/knowledge_item_service.py` - Service pattern example - `python/src/server/api_routes/knowledge_api.py` - API endpoint pattern ### When working on MCP Key files to consider: - `python/src/mcp/mcp_server.py` - MCP server implementation - `python/src/mcp/modules/rag_module.py` - Tool implementations ### When working on RAG Key files to consider: - `python/src/server/services/search/vector_search_service.py` - Vector search logic - `python/src/server/services/embeddings/embedding_service.py` - Embedding generation - `python/src/agents/rag_agent.py` - RAG reranking ### When working on Crawling Key files to consider: - `python/src/server/services/rag/crawling_service.py` - Core crawling logic - `python/src/server/services/knowledge/crawl_orchestration_service.py` - Crawl coordination - `python/src/server/services/storage/document_storage_service.py` - Document storage ### When working on Projects/Tasks Key files to consider: - `python/src/server/services/projects/task_service.py` - Task management - `archon-ui-main/src/components/project-tasks/TaskBoardView.tsx` - Kanban UI ### When working on Agents Key files to consider: - `python/src/agents/base_agent.py` - Agent base class - `python/src/agents/rag_agent.py` - RAG agent implementation ## Critical Rules for This Codebase Follow the guidelines in CLAUDE.md ## Current Focus Areas - The projects feature is optional (toggle in Settings UI) - All services communicate via HTTP, not gRPC - Socket.IO handles all real-time updates - Frontend uses Vite proxy for API calls in development - Python backend uses `uv` for dependency management Remember: This is beta software. Prioritize functionality over production patterns. Make it work, make it right, then make it fast. ================================================ FILE: .claude/commands/archon/archon-rca.md ================================================ --- description: Generate Root Cause Analysis report for Archon V2 Beta issues argument-hint: allowed-tools: Bash(*), Read, Grep, LS, Write thinking: auto --- # Root Cause Analysis for Archon V2 Beta **Issue to investigate**: $ARGUMENTS investigate this issue systematically and generate an RCA report saved to `RCA.md` in the project root. ## Context About Archon You're working with Archon V2 Beta, a microservices-based AI knowledge management system: - **Frontend**: React + TypeScript on port 3737 - **Main Server**: FastAPI + Socket.IO on port 8181 - **MCP Server**: Lightweight HTTP protocol server on port 8051 - **Agents Service**: PydanticAI agents on port 8052 - **Database**: Supabase (PostgreSQL + pgvector) All services run in Docker containers managed by docker-compose. ## Investigation Approach ### 1. Initial Assessment First, understand what's broken: - What exactly is the symptom? - Which service(s) are affected? - When did it start happening? - Is it reproducible? ### 2. System Health Check Check if all services are running properly: - Docker container status (`docker-compose ps`) - Service health endpoints (ports 8181, 8051, 8052, 3737) - Recent error logs from affected services - Database connectivity ### 3. Error Handling Analysis **Remember: In Beta, we want DETAILED ERRORS that help us fix issues fast!** Look for these error patterns: **Good errors (what we want):** - Stack traces with full context - Specific error messages saying what failed - Service initialization failures that stop the system - Validation errors that show what was invalid **Bad patterns (what causes problems):** - Silent failures returning None/null - Generic "Something went wrong" messages - Catch-all exception handlers hiding the real issue - Services continuing with broken dependencies ### 4. Targeted Investigation Based on the issue type, investigate specific areas: **For API/Backend issues**: Check FastAPI routes, service layer, database queries **For Frontend issues**: Check React components, API calls, build process **For MCP issues**: Check tool definitions, session management, HTTP calls **For Real-time issues**: Check Socket.IO connections, event handling **For Database issues**: Check Supabase connection, migrations, RLS policies ### 5. Root Cause Identification - Follow error stack traces to the source - Check if errors are being swallowed somewhere - Look for missing error handling where it should fail fast - Check recent code changes (`git log`) - Identify any dependency or initialization order problems ### 6. Impact Analysis Determine the scope: - Which features are affected? - Is this a startup failure or runtime issue? - Is there data loss or corruption? - Are errors propagating correctly or being hidden? ## Key Places to Look Think hard about where to look, there is some guidance below that you can follow **Configuration files:** - `.env` - Environment variables - `docker-compose.yml` - Service configuration - `python/src/server/config.py` - Server settings **Service entry points:** - `python/src/server/main.py` - Main server - `python/src/mcp/server.py` - MCP server - `archon-ui-main/src/main.tsx` - Frontend **Common problem areas:** - `python/src/server/services/credentials_service.py` - Must initialize first - `python/src/server/services/supabase_service.py` - Database connections - `python/src/server/socketio_manager.py` - Real-time events - `archon-ui-main/src/services/` - Frontend API calls ## Report Structure Generate an RCA.md report with: ```markdown # Root Cause Analysis **Date**: [Today's date] **Issue**: [Brief description] **Severity**: [Critical/High/Medium/Low] ## Summary [One paragraph overview of the issue and its root cause] ## Investigation ### Symptoms - [What was observed] ### Diagnostics Performed - [Health checks run] - [Logs examined] - [Code reviewed] ### Root Cause [Detailed explanation of why this happened] ## Impact - **Services Affected**: [List] - **User Impact**: [Description] - **Duration**: [Time period] ## Resolution ### Immediate Fix [What needs to be done right now] ### Long-term Prevention [How to prevent this in the future] ## Evidence [Key logs, error messages, or code snippets that led to the diagnosis] ## Lessons Learned [What we learned from this incident] ``` ## Helpful Commands ```bash # Check all services docker-compose ps # View recent errors docker-compose logs --tail=50 [service-name] | grep -E "ERROR|Exception" # Health checks curl http://localhost:8181/health curl http://localhost:8051/health # Database test docker-compose exec archon-server python -c "from src.server.services.supabase_service import SupabaseService; print(SupabaseService.health_check())" # Resource usage docker stats --no-stream ``` Remember: Focus on understanding the root cause, not just symptoms. The goal is to create a clear, actionable report that helps prevent similar issues in the future. ================================================ FILE: .claude/commands/archon/archon-ui-consistency-review.md ================================================ --- description: Analyze UI components for reusability, Radix usage, primitives, and styling consistency argument-hint: allowed-tools: Read, Grep, Glob, Write, Bash thinking: auto --- # UI Consistency Review for Archon **Review scope**: $ARGUMENTS ## Process ### Step 1: Load Standards Read `PRPs/ai_docs/UI_STANDARDS.md` - This is the single source of truth for all rules, patterns, and scans. ### Step 2: Find Files Glob all `.tsx` files in the provided path. ### Step 3: Run Automated Scans Execute ALL scans from **UI_STANDARDS.md - AUTOMATED SCAN REFERENCE** section: - Critical scans (dynamic classes, non-responsive grids, native HTML, unconstrained scroll) - High priority scans (keyboard support, dark mode, hardcoded patterns, min-w-0) - Medium priority scans (TypeScript, color mismatches, props validation) ### Step 4: Deep Analysis For each file, check against ALL rules from **UI_STANDARDS.md sections 1-8**: 1. TAILWIND V4 - Static classes, tokens 2. LAYOUT & RESPONSIVE - Grids, scroll, truncation 3. THEMING - Dark mode variants 4. RADIX UI - Primitives usage 5. PRIMITIVES LIBRARY - Card, PillNavigation, styles.ts 6. ACCESSIBILITY - Keyboard, ARIA, focus 7. TYPESCRIPT & API CONTRACTS - Types, props, consistency 8. FUNCTIONAL LOGIC - UI actually works **For primitives** (files in `/features/ui/primitives/`): - Verify all props affect rendering - Check color variant objects have: checked, glow, focusRing, hover - Validate prop implementations match interface ### Step 5: Generate Report Save to `PRPs/reviews/ui-consistency-review-[feature].md` with: - Overall scores (use **UI_STANDARDS.md - SCORING VIOLATIONS**) - Component-by-component analysis - Violations with file:line, current code, required fix - Prioritized action items ### Step 6: Create PRP Use `/prp-claude-code:prp-claude-code-create ui-consistency-fixes-[feature]` if violations found. **PRP should reference:** - The review report - Specific UI_STANDARDS.md sections violated - Automated scan commands to re-run for validation --- **Note**: Do NOT duplicate rules/patterns from UI_STANDARDS.md. Just reference section numbers. ================================================ FILE: .claude/commands/prp-any-agent/prp-any-cli-create.md ================================================ # Create PRP ## Feature file: $ARGUMENTS Generate a complete PRP for general feature implementation with thorough research. Ensure context is passed to the AI agent to enable self-validation and iterative refinement. Read the feature file first to understand what needs to be created, how the examples provided help, and any other considerations. The AI agent only gets the context you are appending to the PRP and training data. Assuma the AI agent has access to the codebase and the same knowledge cutoff as you, so its important that your research findings are included or referenced in the PRP. The Agent has Websearch capabilities, so pass urls to documentation and examples. ## Research Process 1. **Codebase Analysis** - Search for similar features/patterns in the codebase - Identify files to reference in PRP - Note existing conventions to follow - Check test patterns for validation approach 2. **External Research** - Search for similar features/patterns online - Library documentation (include specific URLs) - Implementation examples (GitHub/StackOverflow/blogs) - Best practices and common pitfalls 3. **User Clarification** (if needed) - Specific patterns to mirror and where to find them? - Integration requirements and where to find them? ## PRP Generation Using PRPs/templates/prp_base.md as template: ### Critical Context to Include and pass to the AI agent as part of the PRP - **Documentation**: URLs with specific sections - **Code Examples**: Real snippets from codebase - **Gotchas**: Library quirks, version issues - **Patterns**: Existing approaches to follow ### Implementation Blueprint - Start with pseudocode showing approach - Reference real files for patterns - Include error handling strategy - list tasks to be completed to fullfill the PRP in the order they should be completed ### Validation Gates (Must be Executable) eg for python ```bash # Syntax/Style ruff check --fix && mypy . # Unit Tests uv run pytest tests/ -v ``` **_ CRITICAL AFTER YOU ARE DONE RESEARCHING AND EXPLORING THE CODEBASE BEFORE YOU START WRITING THE PRP _** **_ ULTRATHINK ABOUT THE PRP AND PLAN YOUR APPROACH THEN START WRITING THE PRP _** ## Output Save as: `PRPs/{feature-name}.md` ## Quality Checklist - [ ] All necessary context included - [ ] Validation gates are executable by AI - [ ] References existing patterns - [ ] Clear implementation path - [ ] Error handling documented Score the PRP on a scale of 1-10 (confidence level to succeed in one-pass implementation using claude codes) Remember: The goal is one-pass implementation success through comprehensive context. ================================================ FILE: .claude/commands/prp-any-agent/prp-any-cli-execute.md ================================================ # Execute BASE PRP Implement a feature using using the PRP file. ## PRP File: $ARGUMENTS ## Execution Process 1. **Load PRP** - Read the specified PRP file - Understand all context and requirements - Follow all instructions in the PRP and extend the research if needed - Ensure you have all needed context to implement the PRP fully - Do more web searches and codebase exploration as needed 2. **ULTRATHINK** - Think hard before you execute the plan. Create a comprehensive plan addressing all requirements. - Break down complex tasks into smaller, manageable steps using your todos tools. - Use the TodoWrite tool to create and track your implementation plan. - Identify implementation patterns from existing code to follow. 3. **Execute the plan** - Execute the PRP - Implement all the code 4. **Validate** - Run each validation command - Fix any failures - Re-run until all pass 5. **Complete** - Ensure all checklist items done - Run final validation suite - Report completion status - Read the PRP again to ensure you have implemented everything 6. **Reference the PRP** - You can always reference the PRP again if needed Note: If validation fails, use error patterns in PRP to fix and retry. ================================================ FILE: .claude/commands/prp-claude-code/prp-claude-code-create.md ================================================ # Create BASE PRP ## Feature: $ARGUMENTS ## PRP Creation Mission Create a comprehensive PRP that enables **one-pass implementation success** through systematic research and context curation. **Critical Understanding**: The executing AI agent only receives: - The PRP content you create - Its training data knowledge - Access to codebase files (but needs guidance on which ones) **Therefore**: Your research and context curation directly determines implementation success. Incomplete context = implementation failure. ## Research Process > During the research process, create clear tasks and spawn as many agents and subagents as needed using the batch tools. The deeper research we do here the better the PRP will be. we optminize for chance of success and not for speed. 1. **Codebase Analysis in depth** - Create clear todos and spawn subagents to search the codebase for similar features/patterns Think hard and plan your approach - Identify all the necessary files to reference in the PRP - Note all existing conventions to follow - Check existing test patterns for validation approach - Use the batch tools to spawn subagents to search the codebase for similar features/patterns 2. **External Research at scale** - Create clear todos and spawn with instructions subagents to do deep research for similar features/patterns online and include urls to documentation and examples - Library documentation (include specific URLs) - For critical pieces of documentation add a .md file to PRPs/ai_docs and reference it in the PRP with clear reasoning and instructions - Implementation examples (GitHub/StackOverflow/blogs) - Best practices and common pitfalls found during research - Use the batch tools to spawn subagents to search for similar features/patterns online and include urls to documentation and examples 3. **User Clarification** - Ask for clarification if you need it ## PRP Generation Process ### Step 1: Choose Template Use `PRPs/templates/prp_base.md` as your template structure - it contains all necessary sections and formatting. ### Step 2: Context Completeness Validation Before writing, apply the **"No Prior Knowledge" test** from the template: _"If someone knew nothing about this codebase, would they have everything needed to implement this successfully?"_ ### Step 3: Research Integration Transform your research findings into the template sections: **Goal Section**: Use research to define specific, measurable Feature Goal and concrete Deliverable **Context Section**: Populate YAML structure with your research findings - specific URLs, file patterns, gotchas **Implementation Tasks**: Create dependency-ordered tasks using information-dense keywords from codebase analysis **Validation Gates**: Use project-specific validation commands that you've verified work in this codebase ### Step 4: Information Density Standards Ensure every reference is **specific and actionable**: - URLs include section anchors, not just domain names - File references include specific patterns to follow, not generic mentions - Task specifications include exact naming conventions and placement - Validation commands are project-specific and executable ### Step 5: ULTRATHINK Before Writing After research completion, create comprehensive PRP writing plan using TodoWrite tool: - Plan how to structure each template section with your research findings - Identify gaps that need additional research - Create systematic approach to filling template with actionable context ## Output Save as: `PRPs/{feature-name}.md` ## PRP Quality Gates ### Context Completeness Check - [ ] Passes "No Prior Knowledge" test from template - [ ] All YAML references are specific and accessible - [ ] Implementation tasks include exact naming and placement guidance - [ ] Validation commands are project-specific and verified working ### Template Structure Compliance - [ ] All required template sections completed - [ ] Goal section has specific Feature Goal, Deliverable, Success Definition - [ ] Implementation Tasks follow dependency ordering - [ ] Final Validation Checklist is comprehensive ### Information Density Standards - [ ] No generic references - all are specific and actionable - [ ] File patterns point at specific examples to follow - [ ] URLs include section anchors for exact guidance - [ ] Task specifications use information-dense keywords from codebase ## Success Metrics **Confidence Score**: Rate 1-10 for one-pass implementation success likelihood **Validation**: The completed PRP should enable an AI agent unfamiliar with the codebase to implement the feature successfully using only the PRP content and codebase access. ================================================ FILE: .claude/commands/prp-claude-code/prp-claude-code-execute.md ================================================ # Execute BASE PRP ## PRP File: $ARGUMENTS ## Mission: One-Pass Implementation Success PRPs enable working code on the first attempt through: - **Context Completeness**: Everything needed, nothing guessed - **Progressive Validation**: 4-level gates catch errors early - **Pattern Consistency**: Follow existing codebase approaches **Your Goal**: Transform the PRP into working code that passes all validation gates. ## Execution Process 1. **Load PRP** - Read the specified PRP file completely - Absorb all context, patterns, requirements and gather codebase intelligence - Use the provided documentation references and file patterns, consume the right documentation before the appropriate todo/task - Trust the PRP's context and guidance - it's designed for one-pass success - If needed do additional codebase exploration and research as needed 2. **ULTRATHINK & Plan** - Create comprehensive implementation plan following the PRP's task order - Break down into clear todos using TodoWrite tool - Use subagents for parallel work when beneficial (always create prp inspired prompts for subagents when used) - Follow the patterns referenced in the PRP - Use specific file paths, class names, and method signatures from PRP context - Never guess - always verify the codebase patterns and examples referenced in the PRP yourself 3. **Execute Implementation** - Follow the PRP's Implementation Tasks sequence, add more detail as needed, especially when using subagents - Use the patterns and examples referenced in the PRP - Create files in locations specified by the desired codebase tree - Apply naming conventions from the task specifications and CLAUDE.md 4. **Progressive Validation** **Execute the level validation system from the PRP:** - **Level 1**: Run syntax & style validation commands from PRP - **Level 2**: Execute unit test validation from PRP - **Level 3**: Run integration testing commands from PRP - **Level 4**: Execute specified validation from PRP **Each level must pass before proceeding to the next.** 5. **Completion Verification** - Work through the Final Validation Checklist in the PRP - Verify all Success Criteria from the "What" section are met - Confirm all Anti-Patterns were avoided - Implementation is ready and working **Failure Protocol**: When validation fails, use the patterns and gotchas from the PRP to fix issues, then re-run validation until passing. ================================================ FILE: .claude/commands/prp-claude-code/prp-story-task-create.md ================================================ --- description: "Convert user story/task into executable PRP with deep codebase analysis" --- # Create Story PRP from User Story/Task ## Story/Task: $ARGUMENTS ## Mission Transform a user story or task into a **tactical implementation PRP** through systematic codebase analysis and task decomposition. We do not write any code in this step, the goal is to create a detailed context engineered implementation plan for the implementation agent. **Key Principle**: We must first gather the context about the story/task before proceeding with the analysis. When we understand the story/task, we can proceed with the codebase analysis. We systematically dig deep into the codebase to gather intelligence and identify patterns and implementation points. We then use this information to create a PRP that can be executed by a coding agent. The contents of the created PRP should encapsulate all the information the agent needs to complete the story/task in one pass. Remember that subagents will only receive details from you; the user cannot interact with them directly. Therefore, include all relevant context in the subagent prompt and TODO. Create detailed TODOs and spawn parallel subagents to analyze (use specialized subagents when appropriate). ## Analysis Process ### Phase 1: Story Decomposition Analyze the story to determine: - **Story/Task Type**: Feature/Bug/Enhancement/Refactor - **Complexity**: Low, Medium, High - **Affected Systems**: Which components/services need changes Get a deep understanding about the story/task before proceeding so that you can effectively guide the rest of the process. ### Phase 2: Codebase Intelligence Gathering **1. Project Structure Analysis** - Detect primary language(s) and frameworks - Map directory structure and conventions to identify integration points for the story/task - Identify service/component boundaries - Find configuration files and environment setup **2. Pattern Recognition** - Search for similar implementations in codebase - Identify coding conventions (naming, structure, error handling) start in CLAUDE.md AGENTS.md or relevant rules files such as .cursorrules - Extract common patterns for the story's domain that should be added to the PRP as context for the implementation agent. - Note anti-patterns to avoid **3. Dependency Analysis** - Catalog external libraries used if relevant to the story/task (check package.json, pyproject.toml, go.mod, etc.) - Understand how libraries are integrated - Find relevant documentation in PRPs/ai_docs/ if shared, ai_docs directory is used by the user to paste in relevant additional context that may be relevant to our story/task **4. Testing Patterns** - Identify test framework and structure - Find similar test examples and test setup - Suggest test cases and scenarios **5. Integration Points** - Identify files that will need updates - Identify if new files needs to be created and where to create them - Find router/API registration patterns - Understand database/model patterns if relevant ### Phase 3: Think harder about the story and its components. Really think hard about everything you just learned during the research phases. ### Phase 4: PRP Task Generation Transform analysis into concrete tasks: Read and understand the template @PRPs/templates/prp_story_task.md **Task Rules**: 1. Each task is atomic and independently testable 2. Tasks are ordered by dependency 3. Use action verbs that are information dense: CREATE, UPDATE, ADD, REMOVE, REFACTOR, MIRROR 4. Include specific implementation details from codebase analysis 5. Every task has an executable validation command **Task Action Types**: We use the concept of information dense keywords to describe the action to be taken, below is a guidance. But you can use your own words to describe the action to be taken as long as you follow this same principle. Examples: - **CREATE**: New files/components - **UPDATE**: Modify existing files - **ADD**: Insert new functionality into existing code - **REMOVE**: Delete deprecated code - **REFACTOR**: Restructure without changing behavior - **MIRROR**: Mirror existing pattern or functionality that exists elsewhere in the codebase ### Phase 5: Validation Design For each task, design validation that: - Can run immediately after task completion - Provides clear pass/fail feedback - Uses project-specific commands discovered in analysis ## Quality Criteria ### Task Clarity - [ ] The PRP is clear and concise and follows KISS principle - [ ] Each task has clear action and target - [ ] Implementation details reference specific patterns - [ ] Validation commands are executable ### Context Completeness - [ ] All necessary patterns identified - [ ] External library usage documented - [ ] Integration points mapped - [ ] External context references populated ### Story Coverage - [ ] All acceptance criteria addressed - [ ] Edge cases considered - [ ] Error handling included where needed ## Output Save as: `PRPs/story_{kebab-case-summary}.md` ## Success Metrics **Implementation Ready**: Another developer could execute these tasks without additional context **Validation Complete**: Every task has at least one working validation command **Pattern Consistent**: Tasks follow existing codebase conventions ================================================ FILE: .claude/commands/prp-claude-code/prp-story-task-execute.md ================================================ --- description: "Execute a Story PRP with focused task implementation" --- # Execute Story PRP ## PRP File: $ARGUMENTS ## Mission Execute a story/task PRP through **sequential task completion** with immediate validation. **Execution Philosophy**: Complete one task, validate it, then move to the next. No task left behind. ## Execution Process ### 1. Load Story PRP - Read the specified story PRP file - Understand the original story intent - Review all context references - Note validation commands for each task ### 2. Pre-Implementation Check - Ultrathink about the story intent and task requirements - Verify all referenced files exist - Check that patterns mentioned are accessible - Ensure development environment is ready - Run any pre-requisite setup commands ### 3. Task-by-Task Implementation For each task in the PRP: **a) Understand Task** - Read task requirements completely - Review referenced patterns - Check gotchas and constraints **b) Implement Task** - Follow the specified pattern - Use the indicated naming conventions - Apply the documented approach - Handle edge cases mentioned **c) Validate Immediately** - Run the task's validation command - If validation fails, fix and re-validate - Don't proceed until current task passes **d) Mark Complete** - Update todo list to track progress - Document any deviations if necessary ### 4. Full Validation After all tasks complete: - Run the validation gates from PRP - Execute comprehensive test suite - Verify all acceptance criteria met ### 5. Completion - Work through completion checklist - Ensure story requirements satisfied - Move completed PRP to PRPs/completed/ create the folder if it does not exist ## Execution Rules **Validation Gates**: Each task must pass validation, iterate until passed **Pattern Adherence**: Follow existing patterns, don't create new ones **No Shortcuts**: Complete all validation steps ## Failure Handling When a task fails validation: 1. Read the error message carefully 2. Check the pattern reference again 3. Validate it by investigating the codebase 4. Fix and re-validate 5. If stuck, check similar implementations ## Success Criteria - Every validation command passes - Full test suite green - Story acceptance criteria met - Code follows project conventions ================================================ FILE: .dockerignore ================================================ crawl4ai_mcp.egg-info __pycache__ .venv .env ================================================ FILE: .github/ISSUE_TEMPLATE/auto_bug_report.md ================================================ --- name: Auto Bug Report about: Automated bug report from Archon title: '' labels: bug, auto-report assignees: '' --- ================================================ FILE: .github/ISSUE_TEMPLATE/bug_report.yml ================================================ name: 🐛 Bug Report description: Report a bug to help us improve Archon Beta title: "🐛 [Bug]: " labels: ["bug", "needs-triage"] assignees: [] body: - type: markdown attributes: value: | # 🐛 Bug Report for Archon Beta Thank you for taking the time to report a bug! This helps us improve Archon for everyone. - type: input id: archon-version attributes: label: Archon Version description: What version of Archon are you running? placeholder: "v0.1.0 or check package.json" validations: required: true - type: dropdown id: branch attributes: label: Branch description: Which branch are you using? options: - "stable" - "main" default: 0 validations: required: true - type: dropdown id: severity attributes: label: Bug Severity description: How severe is this bug? options: - "🟢 Low - Minor inconvenience" - "🟡 Medium - Affects functionality" - "🟠 High - Blocks important features" - "🔴 Critical - App unusable" validations: required: true - type: textarea id: description attributes: label: Bug Description description: What were you trying to do when this bug occurred? placeholder: "I was trying to crawl a documentation site when..." validations: required: true - type: textarea id: steps-to-reproduce attributes: label: Steps to Reproduce description: Detailed steps to reproduce the bug placeholder: | 1. Go to Knowledge Base page 2. Click "Add Knowledge" 3. Enter URL: https://example.com 4. Click "Add Source" 5. Error occurs... validations: required: true - type: textarea id: expected-behavior attributes: label: Expected Behavior description: What should have happened? placeholder: "The site should have been crawled successfully and added to my knowledge base..." validations: required: true - type: textarea id: actual-behavior attributes: label: Actual Behavior description: What actually happened? placeholder: "Instead, I got an error message and the crawling failed..." validations: required: true - type: textarea id: error-details attributes: label: Error Details (if any) description: Copy and paste any error messages, stack traces, or console errors placeholder: | Error: Failed to crawl URL at CrawlingService.crawlUrl (/app/src/services/crawling.js:123:15) at async POST /api/knowledge/crawl render: text - type: dropdown id: component attributes: label: Affected Component description: Which part of Archon is affected? options: - "🔍 Knowledge Base / RAG" - "🔗 MCP Integration" - "📋 Projects & Tasks (if enabled)" - "⚙️ Settings & Configuration" - "🖥️ User Interface" - "🐳 Docker / Infrastructure" - "❓ Not Sure" validations: required: true - type: input id: browser-os attributes: label: Browser & OS description: What browser and operating system are you using? placeholder: "Chrome 122 on macOS 14.1" validations: required: true - type: textarea id: additional-context attributes: label: Additional Context description: Any other context about the problem (screenshots, logs, etc.) placeholder: "Add any other context here..." - type: checkboxes id: service-status attributes: label: Service Status (check all that are working) description: Which Archon services were running when the bug occurred? options: - label: "🖥️ Frontend UI (http://localhost:3737)" - label: "⚙️ Main Server (http://localhost:8181)" - label: "🔗 MCP Service (localhost:8051)" - label: "🤖 Agents Service (http://localhost:8052)" - label: "💾 Supabase Database (connected)" ================================================ FILE: .github/RELEASE_NOTES_SETUP.md ================================================ # AI-Generated Release Notes Setup This repository uses Claude AI to automatically generate comprehensive release notes when you create a new release. ## How It Works The workflow triggers when: - You push a new tag (e.g., `v1.0.0`) - You create a GitHub release - You manually trigger it via workflow dispatch Claude AI analyzes: - Commit messages since the last release - Merged pull requests - File changes by component (frontend, backend, docs) - Contributors Then generates structured release notes with: - Overview and key changes - Feature additions, improvements, and bug fixes - Technical changes by component - Statistics and contributor acknowledgments - Breaking changes (important for beta!) ## Testing Locally First (Recommended!) Before setting up the GitHub Action, you can test the release notes generation locally: ### Prerequisites ```bash # Install required tools (if not already installed) sudo apt install jq curl # Linux # or brew install jq curl # macOS # Install GitHub CLI (optional, for PR detection) # See: https://github.com/cli/cli#installation ``` ### Run Local Test ```bash # 1. Export your Anthropic API key export ANTHROPIC_API_KEY="sk-ant-api03-..." # 2. Run the test script # Compare origin/stable vs main branches (default - shows unreleased changes) ./.github/test-release-notes.sh # Or specify branches explicitly (automatically handles remote branches) ./.github/test-release-notes.sh stable main # Will use origin/stable if no local stable ./.github/test-release-notes.sh origin/stable main # Explicit remote branch # Or use range syntax ./.github/test-release-notes.sh stable..main # Or compare tags for a release ./.github/test-release-notes.sh v1.0.0 v2.0.0 # Or test a single tag (compares with previous tag) ./.github/test-release-notes.sh v0.1.0 ``` ### What the Local Test Does 1. **Gathers git data**: Commits, file changes, and PRs (if gh CLI available) 2. **Calls Claude API**: Generates release notes using the same prompt as the workflow 3. **Saves output**: Creates `release-notes-.md` in current directory 4. **Shows preview**: Displays the generated notes in your terminal ### Example Output ```bash $ ./.github/test-release-notes.sh v0.2.0 🤖 Local Release Notes Generator Test ========================================== Current tag: v0.2.0 Previous tag: v0.1.0 📝 Gathering commits... Found 42 commits 📊 Analyzing file changes... Files summary: 28 files changed, 1547 insertions(+), 423 deletions(-) 🔀 Looking for merged PRs... Found 8 merged PRs 🤖 Generating release notes with Claude... ✅ Release notes generated successfully! 📄 Output saved to: release-notes-v0.2.0.md ========================================== Preview: ========================================== [Generated release notes appear here] ========================================== ✅ Done! ``` ### Testing Different Scenarios ```bash # 🔥 MOST COMMON: See what's new in main vs stable (unreleased changes) ./.github/test-release-notes.sh # Output: release-notes-origin-stable..main.md # Or with explicit arguments ./.github/test-release-notes.sh stable main # Output: release-notes-origin-stable..main.md (auto-resolves to origin/stable) # Test your first release (compares with initial commit) ./.github/test-release-notes.sh v0.1.0 # Test a release between two specific tags ./.github/test-release-notes.sh v1.0.0 v2.0.0 # Test what would be in next release (current branch vs stable) git checkout main ./.github/test-release-notes.sh stable main ``` ### Typical Workflow: Stable vs Main For projects with separate `stable` (production) and `main` (development) branches: ```bash # 1. See what's ready to release (compare branches) export ANTHROPIC_API_KEY="sk-ant-..." ./.github/test-release-notes.sh stable main # Or explicitly use remote branch: ./.github/test-release-notes.sh origin/stable main # 2. Review the generated notes cat release-notes-origin-stable..main.md # 3. When ready to release, fetch latest and merge main to stable git fetch origin git checkout -b stable origin/stable # Create local tracking branch if needed git merge main git push origin stable # 4. Create a release tag git tag v1.0.0 git push origin v1.0.0 # 5. The GitHub Action will automatically generate release notes # (You can also manually create the release with the generated notes) gh release create v1.0.0 --title "Release v1.0.0" --notes-file release-notes-origin-stable..main.md ``` ## Setup Instructions ### 1. Get Claude Code OAuth Token The GitHub Action uses Claude Code OAuth token (same as the `claude-review` workflow): 1. Go to [Claude Code OAuth Setup](https://docs.anthropic.com/claude-code/oauth) 2. Follow the instructions to get your OAuth token 3. Copy the token ### 2. Add GitHub Secret 1. Go to your repository's Settings 2. Navigate to **Secrets and variables** → **Actions** 3. Click **New repository secret** 4. Name: `CLAUDE_CODE_OAUTH_TOKEN` 5. Value: Paste your Claude Code OAuth token 6. Click **Add secret** > **Note:** If you already have `CLAUDE_CODE_OAUTH_TOKEN` set up for `claude-review` workflow, you're all set! The same token is used for both workflows. ### 3. (Optional) Get Anthropic API Key for Local Testing For local testing, you'll need an API key: 1. Go to [Anthropic Console](https://console.anthropic.com/) 2. Create a new API key 3. Copy the key (starts with `sk-ant-...`) 4. Export it: `export ANTHROPIC_API_KEY="sk-ant-..."` > **Note:** The GitHub Action uses OAuth token, but local testing uses API key for simplicity. ### 4. Test the Workflow #### Option A: Create a Release via GitHub UI 1. Go to **Releases** in your repository 2. Click **Draft a new release** 3. Choose or create a tag (e.g., `v0.1.0`) 4. Click **Publish release** 5. The workflow will automatically run and update the release notes #### Option B: Push a Tag via Git ```bash # Create and push a new tag git tag v0.1.0 git push origin v0.1.0 # The workflow will automatically create a release with AI-generated notes ``` #### Option C: Manual Trigger 1. Go to **Actions** tab 2. Select "AI-Generated Release Notes" workflow 3. Click **Run workflow** 4. Enter the tag name (e.g., `v0.1.0`) 5. Click **Run workflow** ## Usage Examples ### Creating Your First Release ```bash # Tag your current state git tag v0.1.0-beta # Push the tag git push origin v0.1.0-beta # Check Actions tab - release notes will be generated automatically ``` ### Creating Subsequent Releases ```bash # Make your changes and commits git add . git commit -m "feat: Add AI-powered search feature" git push # When ready to release git tag v0.2.0-beta git push origin v0.2.0-beta # Release notes will compare v0.2.0-beta with v0.1.0-beta ``` ## What Gets Generated The AI generates release notes in this structure: ```markdown # 🚀 Release v0.2.0 ## 📝 Overview [Summary of the release] ## ✨ What's New ### Major Features - [New features] ### Improvements - [Enhancements] ### Bug Fixes - [Fixes] ## 🔧 Technical Changes ### Backend (Python/FastAPI) - [Backend changes] ### Frontend (React/TypeScript) - [Frontend changes] ### Infrastructure - [Infrastructure updates] ## 📊 Statistics - Commits: X - Pull Requests: Y - Files Changed: Z - Contributors: N ## 🙏 Contributors [List of contributors] ## ⚠️ Breaking Changes [Any breaking changes] ## 🔗 Links - Full Changelog: [link] ``` ## Customization ### Modify the Prompt Edit `.github/workflows/release-notes.yml` and change the prompt in the "Generate release notes with Claude" step to adjust: - Tone and style - Structure - Focus areas - Level of detail ### Change Claude Model In the workflow file, you can change the model: ```yaml "model": "claude-sonnet-4-20250514" # Latest Sonnet # or "model": "claude-3-7-sonnet-20250219" # Sonnet 3.7 # or "model": "claude-opus-4-20250514" # Opus 4 (more detailed) ``` ### Adjust Token Limit Increase `max_tokens` for longer release notes: ```yaml "max_tokens": 4096 # Default # or "max_tokens": 8192 # For more detailed notes ``` ## Troubleshooting ### Workflow Fails with "ANTHROPIC_API_KEY not found" - Ensure you've added the secret in repository settings - Secret name must be exactly `ANTHROPIC_API_KEY` - Secret must be a valid Anthropic API key ### Empty or Incomplete Release Notes - Check if commits exist between tags - Verify git history is complete (workflow uses `fetch-depth: 0`) - Check Actions logs for API errors ### API Rate Limits - Anthropic has generous rate limits for API keys - For very frequent releases, consider caching or batching ## Authentication: GitHub Action vs Local Testing ### GitHub Action (Claude Code OAuth) - Uses `CLAUDE_CODE_OAUTH_TOKEN` secret - Same authentication as `claude-review` workflow - Integrated with GitHub through Claude Code Action - No direct API costs (usage included with Claude Code) ### Local Testing (API Key) - Uses `ANTHROPIC_API_KEY` environment variable - Direct API calls to Claude - Simpler for local testing and debugging - Cost: ~$0.003 per release (less than a penny) ### Why Two Methods? - **GitHub Action**: Uses Claude Code Action for better GitHub integration and consistency with other workflows - **Local Testing**: Uses direct API for simplicity and faster iteration during development ## Cost Estimation ### Local Testing (API Key) Claude API pricing (as of 2025): - Sonnet 4: ~$0.003 per release (assuming ~4K tokens) - Each release generation costs less than a penny - For a project with monthly releases: ~$0.036/year ### GitHub Action (OAuth Token) - No additional costs beyond your Claude Code subscription - Usage included in Claude Code plan ## Best Practices ### Write Good Commit Messages The AI works better with clear commits: ```bash # ✅ Good git commit -m "feat: Add vector search with pgvector" git commit -m "fix: Resolve race condition in crawling service" git commit -m "docs: Update API documentation" # ❌ Less helpful git commit -m "updates" git commit -m "fix stuff" git commit -m "wip" ``` ### Use Conventional Commits The workflow benefits from conventional commit format: - `feat:` - New features - `fix:` - Bug fixes - `docs:` - Documentation - `refactor:` - Code refactoring - `test:` - Tests - `chore:` - Maintenance ### Tag Semantically Use semantic versioning: - `v1.0.0` - Major release - `v1.1.0` - Minor release (new features) - `v1.1.1` - Patch release (bug fixes) - `v0.1.0-beta` - Beta releases ## Manual Editing You can always edit the generated release notes: 1. Go to the release page 2. Click **Edit release** 3. Modify the notes as needed 4. Click **Update release** ## Workflow Outputs The workflow provides: - Updated GitHub release with AI-generated notes - Artifact with release notes (kept for 90 days) - Comments on related PRs linking to the release - Summary in Actions tab ## Advanced: Using with Pre-releases ```bash # Create a pre-release git tag v0.2.0-rc.1 git push origin v0.2.0-rc.1 # Mark as pre-release in GitHub UI or via gh CLI gh release create v0.2.0-rc.1 --prerelease ``` ## Integration with Other Tools ### Notify Slack/Discord Add a notification step after release creation: ```yaml - name: Notify team run: | curl -X POST YOUR_WEBHOOK_URL \ -H 'Content-Type: application/json' \ -d '{"text":"Release ${{ steps.get_tag.outputs.tag }} published!"}' ``` ### Update Changelog File Append to CHANGELOG.md: ```yaml - name: Update changelog run: | cat release_notes.md >> CHANGELOG.md git add CHANGELOG.md git commit -m "docs: Update changelog for ${{ steps.get_tag.outputs.tag }}" git push ``` ## Support If you encounter issues: 1. Check the workflow logs in Actions tab 2. Verify your API key is valid 3. Ensure git history is available 4. Open an issue with workflow logs attached ================================================ FILE: .github/pull_request_template.md ================================================ # Pull Request ## Summary ## Changes Made - - - ## Type of Change - [ ] Bug fix (non-breaking change which fixes an issue) - [ ] New feature (non-breaking change which adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected) - [ ] Documentation update - [ ] Performance improvement - [ ] Code refactoring ## Affected Services - [ ] Frontend (React UI) - [ ] Server (FastAPI backend) - [ ] MCP Server (Model Context Protocol) - [ ] Agents (PydanticAI service) - [ ] Database (migrations/schema) - [ ] Docker/Infrastructure - [ ] Documentation site ## Testing - [ ] All existing tests pass - [ ] Added new tests for new functionality - [ ] Manually tested affected user flows - [ ] Docker builds succeed for all services ### Test Evidence ```bash # Example: python -m pytest tests/ # Example: cd archon-ui-main && npm run test ``` ## Checklist - [ ] My code follows the service architecture patterns - [ ] If using an AI coding assistant, I used the CLAUDE.md rules - [ ] I have added tests that prove my fix/feature works - [ ] All new and existing tests pass locally - [ ] My changes generate no new warnings - [ ] I have updated relevant documentation - [ ] I have verified no regressions in existing features ## Breaking Changes ## Additional Notes ================================================ FILE: .github/test-release-notes.sh ================================================ #!/bin/bash set -e # Colors for output RED='\033[0;31m' GREEN='\033[0;32m' YELLOW='\033[1;33m' BLUE='\033[0;34m' NC='\033[0m' # No Color echo -e "${BLUE}🤖 Local Release Notes Generator Test${NC}" echo "==========================================" echo # Check for required tools command -v jq >/dev/null 2>&1 || { echo -e "${RED}❌ jq is required but not installed. Install with: apt install jq${NC}" >&2; exit 1; } command -v curl >/dev/null 2>&1 || { echo -e "${RED}❌ curl is required but not installed.${NC}" >&2; exit 1; } # Check for API key if [ -z "$ANTHROPIC_API_KEY" ]; then echo -e "${RED}❌ ANTHROPIC_API_KEY environment variable not set${NC}" echo -e "${YELLOW}Export your key first: export ANTHROPIC_API_KEY=sk-ant-...${NC}" exit 1 fi # Parse arguments for branch/tag comparison if [ -n "$2" ]; then # Two arguments: compare from $1 to $2 PREVIOUS_TAG="$1" CURRENT_TAG="$2" echo -e "${GREEN}Comparing: $PREVIOUS_TAG → $CURRENT_TAG${NC}" IS_FIRST_RELEASE="false" elif [ -n "$1" ]; then # One argument - could be a tag or a range if [[ "$1" == *".."* ]]; then # Range format: stable..main PREVIOUS_TAG="${1%%..*}" CURRENT_TAG="${1##*..}" echo -e "${GREEN}Comparing range: $PREVIOUS_TAG → $CURRENT_TAG${NC}" else # Single tag/branch - compare with previous tag or initial commit CURRENT_TAG="$1" PREVIOUS_TAG=$(git tag --sort=-v:refname | grep -A1 "^${CURRENT_TAG}$" | tail -1) if [ -z "$PREVIOUS_TAG" ] || [ "$PREVIOUS_TAG" == "$CURRENT_TAG" ]; then PREVIOUS_TAG=$(git rev-list --max-parents=0 HEAD) IS_FIRST_RELEASE="true" echo -e "${YELLOW}First release - comparing against initial commit${NC}" else IS_FIRST_RELEASE="false" echo -e "${GREEN}Current: $CURRENT_TAG, Previous: $PREVIOUS_TAG${NC}" fi fi IS_FIRST_RELEASE="false" else # No arguments - default to origin/stable..main comparison PREVIOUS_TAG="origin/stable" CURRENT_TAG="main" echo -e "${BLUE}No arguments provided - comparing branches: origin/stable → main${NC}" echo -e "${YELLOW}Usage:${NC}" echo -e "${YELLOW} $0 # Compare origin/stable..main (default)${NC}" echo -e "${YELLOW} $0 origin/stable main # Compare two branches${NC}" echo -e "${YELLOW} $0 origin/stable..main # Range syntax${NC}" echo -e "${YELLOW} $0 v1.0.0 # Compare with previous tag${NC}" echo -e "${YELLOW} $0 v1.0.0 v2.0.0 # Compare two tags${NC}" echo IS_FIRST_RELEASE="false" fi # Normalize branch/tag references (handle remote branches) # If a branch name doesn't exist locally, try origin/ normalize_ref() { local ref="$1" # If it already has origin/ prefix or is a commit hash, use as-is if [[ "$ref" == origin/* ]] || git rev-parse -q --verify "$ref" >/dev/null 2>&1; then echo "$ref" return fi # Try local branch first if git rev-parse -q --verify "$ref" >/dev/null 2>&1; then echo "$ref" return fi # Try as remote branch if git rev-parse -q --verify "origin/$ref" >/dev/null 2>&1; then echo "origin/$ref" return fi # Return original if nothing works (will fail later with clear error) echo "$ref" } PREVIOUS_TAG=$(normalize_ref "$PREVIOUS_TAG") CURRENT_TAG=$(normalize_ref "$CURRENT_TAG") echo -e "${GREEN}Comparing: ${PREVIOUS_TAG} → ${CURRENT_TAG}${NC}" echo # Get commit messages echo -e "${BLUE}📝 Gathering commits...${NC}" COMMITS=$(git log ${PREVIOUS_TAG}..${CURRENT_TAG} --pretty=format:"- %s (%h) by %an" --no-merges) COMMIT_COUNT=$(echo "$COMMITS" | wc -l) echo -e "${GREEN}Found $COMMIT_COUNT commits${NC}" # Get file changes echo -e "${BLUE}📊 Analyzing file changes...${NC}" FILES_CHANGED=$(git diff ${PREVIOUS_TAG}..${CURRENT_TAG} --stat | tail -1) # Detailed changes by component CHANGES_FRONTEND=$(git diff ${PREVIOUS_TAG}..${CURRENT_TAG} --stat -- archon-ui-main/ | head -20) CHANGES_BACKEND=$(git diff ${PREVIOUS_TAG}..${CURRENT_TAG} --stat -- python/ | head -20) FILE_CHANGES="### File Changes by Component **Frontend:** $CHANGES_FRONTEND **Backend:** $CHANGES_BACKEND" echo -e "${GREEN}Files summary: $FILES_CHANGED${NC}" # Get merged PRs (using gh CLI if available) echo -e "${BLUE}🔀 Looking for merged PRs...${NC}" if command -v gh >/dev/null 2>&1; then PREV_DATE=$(git log -1 --format=%ai ${PREVIOUS_TAG}) PRS=$(gh pr list \ --state merged \ --limit 100 \ --json number,title,mergedAt,author,url \ --jq --arg date "$PREV_DATE" \ '.[] | select(.mergedAt >= $date) | "- #\(.number): \(.title) by @\(.author.login) - \(.url)"' \ 2>/dev/null || echo "No PRs found or unable to fetch") PR_COUNT=$(echo "$PRS" | grep -c '^-' || echo "0") echo -e "${GREEN}Found $PR_COUNT merged PRs${NC}" else PRS="No PRs fetched (gh CLI not available)" echo -e "${YELLOW}gh CLI not available - skipping PR detection${NC}" fi echo # Get repository info REPO_FULL=$(git config --get remote.origin.url | sed 's/.*github.com[:/]\(.*\)\.git/\1/') REPO_OWNER=$(echo "$REPO_FULL" | cut -d'/' -f1) REPO_NAME=$(echo "$REPO_FULL" | cut -d'/' -f2) # Create prompt for Claude echo -e "${BLUE}🤖 Generating release notes with Claude...${NC}" # Build the prompt content PROMPT_CONTENT="You are writing release notes for Archon V2 Beta, a local-first AI knowledge management system. ## Release Information **Version:** ${CURRENT_TAG} **Previous Version:** ${PREVIOUS_TAG} **Commits:** ${COMMIT_COUNT} **Is First Release:** ${IS_FIRST_RELEASE} ## Commits \`\`\` ${COMMITS} \`\`\` ## Pull Requests Merged \`\`\` ${PRS} \`\`\` ## File Changes \`\`\` ${FILE_CHANGES} \`\`\` ## Instructions Generate comprehensive release notes following this structure: # 🚀 Release ${CURRENT_TAG} ## 📝 Overview [2-3 sentence summary of this release] ## ✨ What's New ### Major Features - [List major new features with brief descriptions] ### Improvements - [List improvements and enhancements] ### Bug Fixes - [List bug fixes] ## 🔧 Technical Changes ### Backend (Python/FastAPI) - [Notable backend changes] ### Frontend (React/TypeScript) - [Notable frontend changes] ### Infrastructure - [Docker, CI/CD, deployment changes] ## 📊 Statistics - **Commits:** ${COMMIT_COUNT} - **Pull Requests:** [Count from PRs list] - **Files Changed:** [From file stats] - **Contributors:** [Unique authors from commits] ## 🙏 Contributors Thanks to everyone who contributed to this release: [List unique contributors with @ mentions] ## ⚠️ Breaking Changes [List any breaking changes - this is beta software, so breaking changes are expected] ## 🔗 Links - **Full Changelog:** https://github.com/${REPO_FULL}/compare/${PREVIOUS_TAG}...${CURRENT_TAG} - **Installation Guide:** [Link to docs] --- **Note:** This is a beta release. Features may change rapidly. Report issues at: https://github.com/${REPO_FULL}/issues --- Write in a professional yet enthusiastic tone. Focus on user-facing changes. Be specific but concise." # Create the request using jq to properly escape JSON jq -n \ --arg model "claude-sonnet-4-20250514" \ --arg content "$PROMPT_CONTENT" \ '{ model: $model, max_tokens: 4096, temperature: 0.7, messages: [ { role: "user", content: $content } ] }' > /tmp/claude_request.json # Call Claude API RESPONSE=$(curl -s https://api.anthropic.com/v1/messages \ -H "Content-Type: application/json" \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -d @/tmp/claude_request.json) # Check for errors if echo "$RESPONSE" | jq -e '.error' >/dev/null 2>&1; then echo -e "${RED}❌ API Error:${NC}" echo "$RESPONSE" | jq '.error' exit 1 fi # Extract release notes RELEASE_NOTES=$(echo "$RESPONSE" | jq -r '.content[0].text') if [ -z "$RELEASE_NOTES" ] || [ "$RELEASE_NOTES" == "null" ]; then echo -e "${RED}❌ Failed to extract release notes from response${NC}" echo "Response:" echo "$RESPONSE" | jq . exit 1 fi # Save to file # Create safe filename from branch/tag names SAFE_FROM=$(echo "$PREVIOUS_TAG" | tr '/' '-') SAFE_TO=$(echo "$CURRENT_TAG" | tr '/' '-') OUTPUT_FILE="release-notes-${SAFE_FROM}..${SAFE_TO}.md" echo "$RELEASE_NOTES" > "$OUTPUT_FILE" echo -e "${GREEN}✅ Release notes generated successfully!${NC}" echo echo -e "${BLUE}📄 Output saved to: ${OUTPUT_FILE}${NC}" echo echo "==========================================" echo -e "${YELLOW}Preview:${NC}" echo "==========================================" cat "$OUTPUT_FILE" echo echo "==========================================" echo -e "${GREEN}✅ Done!${NC}" echo echo "To create a GitHub release with these notes:" echo -e "${YELLOW}gh release create ${CURRENT_TAG} --title 'Release ${CURRENT_TAG}' --notes-file ${OUTPUT_FILE}${NC}" ================================================ FILE: .github/workflows/ci.yml ================================================ name: Continuous Integration on: push: branches: [ main, unit-testing-ci ] pull_request: branches: [ main ] workflow_dispatch: # Allow manual triggering env: # Test database credentials (using properly formatted fake values for CI) # These are fake but properly formatted values that will pass validation SUPABASE_URL: ${{ secrets.SUPABASE_URL || 'https://xyzcompanytest.supabase.co' }} SUPABASE_SERVICE_KEY: ${{ secrets.SUPABASE_SERVICE_KEY || 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZS1kZW1vIiwicm9sZSI6InNlcnZpY2Vfcm9sZSIsImV4cCI6MTk4MzgxMjk5Nn0.EGIM96RAZx35lJzdJsyH-qQwv8Hdp7fsn3W0YpN81IU' }} NODE_VERSION: '18' PYTHON_VERSION: '3.12' jobs: # Job 1: Frontend Testing (React/TypeScript/Vitest) # Will enable this after overhaul of frontend for linting frontend-tests: name: Frontend Tests (React + Vitest) runs-on: ubuntu-latest defaults: run: working-directory: ./archon-ui-main steps: - name: Checkout repository uses: actions/checkout@v4 - name: Setup Node.js uses: actions/setup-node@v4 with: node-version: ${{ env.NODE_VERSION }} cache: 'npm' cache-dependency-path: archon-ui-main/package-lock.json - name: Install dependencies run: npm ci # - name: Run ESLint # run: npm run lint # # - name: Run TypeScript type check # run: npx tsc --noEmit # # - name: Run Vitest tests with coverage # run: npm run test:coverage:run # # - name: Generate test summary # if: always() # run: npm run test:coverage:summary # # - name: Upload frontend test results # if: always() # uses: actions/upload-artifact@v4 # with: # name: frontend-test-results # path: | # archon-ui-main/coverage/test-results.json # archon-ui-main/public/test-results/ # retention-days: 30 # # - name: Upload frontend coverage to Codecov # if: always() # uses: codecov/codecov-action@v4 # with: # files: ./archon-ui-main/public/test-results/coverage/lcov.info # flags: frontend # name: frontend-coverage # token: ${{ secrets.CODECOV_TOKEN }} # Job 2: Backend Testing (Python/pytest) backend-tests: name: Backend Tests (Python + pytest) runs-on: ubuntu-latest defaults: run: working-directory: ./python steps: - name: Checkout repository uses: actions/checkout@v4 - name: Install uv uses: astral-sh/setup-uv@v4 with: version: "latest" - name: Set up Python run: uv python install ${{ env.PYTHON_VERSION }} - name: Install dependencies run: | uv sync --group all --group dev uv add pytest-cov - name: Run linting with ruff (if available) continue-on-error: true run: | if uv run which ruff > /dev/null 2>&1; then echo "Running ruff linting..." uv run ruff check src/ tests/ || true else echo "Ruff not found, skipping linting" fi - name: Run type checking with mypy (if available) continue-on-error: true run: | if uv run which mypy > /dev/null 2>&1; then echo "Running mypy type checking..." uv run mypy src/ || true else echo "MyPy not found, skipping type checking" fi - name: Run all tests run: | echo "Running all unit tests..." uv run pytest tests/ --verbose --tb=short \ --cov=src --cov-report=xml --cov-report=html \ --cov-report=term-missing \ --junitxml=test-results.xml - name: Upload backend test results if: always() uses: actions/upload-artifact@v4 with: name: backend-test-results path: | python/test-results.xml python/htmlcov/ python/coverage.xml retention-days: 30 - name: Upload backend coverage to Codecov if: always() uses: codecov/codecov-action@v4 with: files: ./python/coverage.xml flags: backend name: backend-coverage token: ${{ secrets.CODECOV_TOKEN }} # Job 3: Docker Build Test docker-build-test: name: Docker Build Tests runs-on: ubuntu-latest strategy: matrix: service: [server, mcp, agents, frontend] steps: - name: Checkout repository uses: actions/checkout@v4 - name: Set up Docker Buildx uses: docker/setup-buildx-action@v3 - name: Build server service if: matrix.service == 'server' run: | docker build \ --file python/Dockerfile.server \ --tag archon-server:test \ --build-arg BUILDKIT_INLINE_CACHE=1 \ --build-arg ARCHON_SERVER_PORT=8181 \ python/ - name: Build MCP service if: matrix.service == 'mcp' run: | docker build \ --file python/Dockerfile.mcp \ --tag archon-mcp:test \ --build-arg BUILDKIT_INLINE_CACHE=1 \ --build-arg ARCHON_MCP_PORT=8051 \ python/ - name: Build agents service if: matrix.service == 'agents' run: | docker build \ --file python/Dockerfile.agents \ --tag archon-agents:test \ --build-arg BUILDKIT_INLINE_CACHE=1 \ --build-arg ARCHON_AGENTS_PORT=8052 \ python/ - name: Build frontend service if: matrix.service == 'frontend' run: | docker build \ --tag archon-frontend:test \ archon-ui-main/ - name: Test container health check (for the containers that can run without proper env vars) if: matrix.service != 'frontend' && matrix.service != 'server' run: | # Only test MCP and agents services (they don't require real Supabase connection) # Skip server and frontend as they need real database case "${{ matrix.service }}" in "mcp") docker run -d --name test-${{ matrix.service }} \ -e SUPABASE_URL=${{ env.SUPABASE_URL }} \ -e SUPABASE_SERVICE_KEY=${{ env.SUPABASE_SERVICE_KEY }} \ -e ARCHON_MCP_PORT=8051 \ -e API_SERVICE_URL=http://localhost:8181 \ -e AGENTS_SERVICE_URL=http://localhost:8052 \ -p 8051:8051 \ archon-${{ matrix.service }}:test ;; "agents") docker run -d --name test-${{ matrix.service }} \ -e SUPABASE_URL=${{ env.SUPABASE_URL }} \ -e SUPABASE_SERVICE_KEY=${{ env.SUPABASE_SERVICE_KEY }} \ -e ARCHON_AGENTS_PORT=8052 \ -p 8052:8052 \ archon-${{ matrix.service }}:test ;; esac # Wait for container to start sleep 30 # Check if container is still running if docker ps | grep -q test-${{ matrix.service }}; then echo "✅ Container test-${{ matrix.service }} is running" else echo "❌ Container test-${{ matrix.service }} failed to start" docker logs test-${{ matrix.service }} exit 1 fi - name: Cleanup test containers if: always() run: | docker stop test-${{ matrix.service }} || true docker rm test-${{ matrix.service }} || true # Job 4: Test Results Summary test-summary: name: Test Results Summary runs-on: ubuntu-latest needs: [frontend-tests, backend-tests, docker-build-test] if: always() steps: - name: Download all artifacts uses: actions/download-artifact@v4 - name: Create test summary run: | echo "# 🧪 Archon V2 Beta - CI Test Results" >> $GITHUB_STEP_SUMMARY echo "" >> $GITHUB_STEP_SUMMARY # Frontend Results echo "## 🎨 Frontend Tests (React + Vitest)" >> $GITHUB_STEP_SUMMARY if [ -f "frontend-test-results/coverage/test-results.json" ]; then echo "✅ Frontend tests completed" >> $GITHUB_STEP_SUMMARY else echo "❌ Frontend tests failed or incomplete" >> $GITHUB_STEP_SUMMARY fi echo "" >> $GITHUB_STEP_SUMMARY # Backend Results echo "## 🐍 Backend Tests (Python + pytest)" >> $GITHUB_STEP_SUMMARY if [ -d "backend-test-results-unit" ]; then echo "✅ Unit tests completed" >> $GITHUB_STEP_SUMMARY else echo "❌ Unit tests failed or incomplete" >> $GITHUB_STEP_SUMMARY fi if [ -d "backend-test-results-integration" ]; then echo "✅ Integration tests completed" >> $GITHUB_STEP_SUMMARY else echo "❌ Integration tests failed or incomplete" >> $GITHUB_STEP_SUMMARY fi echo "" >> $GITHUB_STEP_SUMMARY # Docker Build Results echo "## 🐳 Docker Build Tests" >> $GITHUB_STEP_SUMMARY echo "Docker build tests completed - check individual job results" >> $GITHUB_STEP_SUMMARY echo "" >> $GITHUB_STEP_SUMMARY # Coverage Information echo "## 📊 Coverage Reports" >> $GITHUB_STEP_SUMMARY echo "Coverage reports have been uploaded to Codecov and are available as artifacts." >> $GITHUB_STEP_SUMMARY echo "" >> $GITHUB_STEP_SUMMARY # Architecture Context echo "## 🏗️ Architecture Tested" >> $GITHUB_STEP_SUMMARY echo "- **Frontend**: React + TypeScript + Vite (Port 3737)" >> $GITHUB_STEP_SUMMARY echo "- **Server**: FastAPI + Socket.IO + Python (Port 8181)" >> $GITHUB_STEP_SUMMARY echo "- **MCP Service**: MCP protocol server (Port 8051)" >> $GITHUB_STEP_SUMMARY echo "- **Agents Service**: PydanticAI agents (Port 8052)" >> $GITHUB_STEP_SUMMARY echo "- **Database**: Supabase (PostgreSQL + pgvector)" >> $GITHUB_STEP_SUMMARY ================================================ FILE: .github/workflows/claude-fix.yml ================================================ name: Claude Code Fix (Write Access) on: issue_comment: types: [created] pull_request_review_comment: types: [created] jobs: claude-fix: # Only trigger on @claude-fix command from authorized users if: | ( github.event_name == 'issue_comment' || github.event_name == 'pull_request_review_comment' ) && contains(github.event.comment.body, '@claude-fix') && contains(fromJSON('["Wirasm", "coleam00", "sean-eskerium"]'), github.event.comment.user.login) runs-on: ubuntu-latest permissions: contents: write # Allow creating branches and editing files pull-requests: write # Allow creating and updating pull requests issues: write # Allow commenting on and updating issues id-token: write # Required for OIDC authentication actions: read # Read CI results steps: - name: Checkout repository uses: actions/checkout@v4 with: fetch-depth: 0 # Full history for better context - name: Run Claude Code Fix id: claude uses: anthropics/claude-code-action@beta timeout-minutes: 30 with: claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} # Custom trigger phrase for fix workflow trigger_phrase: "@claude-fix" # Fix-specific instructions custom_instructions: | You are authorized to IMPLEMENT FIXES and CREATE PULL REQUESTS. ## Your Role You are fixing issues in Archon V2 Beta. Follow CLAUDE.md for project principles and commands. ## Architecture Context - Frontend: React + TypeScript + Vite (port 3737) - Backend: FastAPI + Socket.IO + Python (port 8181) - MCP Service: MCP protocol server (port 8051) - Agents Service: PydanticAI agents (port 8052) - Database: Supabase (PostgreSQL + pgvector) ## Fix Workflow - MINIMAL CHANGES ONLY ### 1. ROOT CAUSE ANALYSIS (RCA) - **Reproduce**: Can you reproduce the issue? If not, state why - **Identify**: Use ripgrep to search for error messages, function names, patterns - **Trace**: Follow the execution path using git blame and code navigation - **Root Cause**: What is the ACTUAL cause vs symptoms? - Is it a typo/syntax error? - Is it a logic error? - Is it a missing dependency? - Is it a type mismatch? - Is it an async/timing issue? - Is it a state management issue? ### 2. MINIMAL FIX STRATEGY - **Scope**: Fix ONLY the root cause, nothing else - **Pattern Match**: Look for similar code in the codebase - follow existing patterns - **Side Effects**: Will this break anything else? Check usages with ripgrep - **Alternative**: If fix seems too invasive, document alternative approaches ### 3. IMPLEMENTATION - Create branch: `fix/issue-{number}` or `fix/pr-{number}-{description}` or `fix/{brief-description}` - Make the minimal change that fixes the root cause - If existing tests break, understand why before changing them - Add test to prevent regression (especially for bug fixes) ### 4. VERIFICATION LOOP - Run tests according to CLAUDE.md commands - If tests fail: - Analyze why they failed - Is it your fix or unrelated? - Fix and retry until all green - If fix breaks something else: - Do another RCA on the new issue - Consider alternative approach - Document tradeoffs in PR ### 5. PULL REQUEST Use the template in .github/pull_request_template.md: - Fill all sections accurately - Mark type as "Bug fix" - Show test evidence with actual command outputs - If can't fix completely, document what's blocking in Additional Notes ## Decision Points - **Don't fix if**: Needs product decision, requires major refactoring, or changes core architecture - **Document blockers**: If something prevents a complete fix, explain in PR - **Ask for guidance**: Use PR description to ask questions if uncertain ## Remember - The person triggering this workflow wants a fix - deliver one or explain why you can't - Follow CLAUDE.md for all commands and project principles - Prefer ripgrep over grep for searching - Keep changes minimal - resist urge to refactor - Beta project: Quick fixes over perfect solutions # Commented out - using default tools # allowed_tools: "Edit(*),MultiEdit(*),Write(*),Read(*),Grep(*),LS(*),Glob(*),TodoWrite(*),NotebookEdit(*),Bash(git *),Bash(npm *),Bash(uv *),Bash(python *),Bash(pip *),Bash(cd *),Bash(pwd),Bash(ls *),Bash(cat *),Bash(head *),Bash(tail *),Bash(wc *),Bash(find *),Bash(grep *),Bash(rg *),Bash(sed *),Bash(awk *),Bash(curl *),Bash(wget *),Bash(echo *),Bash(mkdir *),Bash(rm -rf node_modules),Bash(rm -rf __pycache__),Bash(rm -rf .pytest_cache),WebSearch(*),WebFetch(*)" unauthorized-message: # Post message for unauthorized users if: | ( github.event_name == 'issue_comment' || github.event_name == 'pull_request_review_comment' ) && contains(github.event.comment.body, '@claude-fix') && !contains(fromJSON('["Wirasm", "coleam00", "sean-eskerium"]'), github.event.comment.user.login) runs-on: ubuntu-latest permissions: issues: write pull-requests: write steps: - name: Post unauthorized message uses: actions/github-script@v7 with: script: | const comment = { owner: context.repo.owner, repo: context.repo.repo, body: `❌ @${context.actor} - You are not authorized to trigger Claude fixes.\n\nOnly maintainers can trigger Claude: Please ask a maintainer to run the fix command.` }; if (context.eventName === 'issue_comment') { await github.rest.issues.createComment({ ...comment, issue_number: context.issue.number }); } else if (context.eventName === 'pull_request_review_comment') { await github.rest.pulls.createReplyForReviewComment({ owner: context.repo.owner, repo: context.repo.repo, pull_number: context.payload.pull_request.number, comment_id: context.payload.comment.id, body: comment.body }); } ================================================ FILE: .github/workflows/claude-review.yml ================================================ name: Claude Code Review (Read-Only) on: issue_comment: types: [created] pull_request_review_comment: types: [created] jobs: claude-review: # Only trigger on @claude-review command from authorized users if: | ( github.event_name == 'issue_comment' || github.event_name == 'pull_request_review_comment' ) && contains(github.event.comment.body, '@claude-review') && contains(fromJSON('["Wirasm", "coleam00", "sean-eskerium"]'), github.event.comment.user.login) runs-on: ubuntu-latest permissions: contents: read # Read-only access pull-requests: write # Allow comments on PRs issues: write # Allow comments on issues actions: read # Read CI results id-token: write # Required for OIDC authentication steps: - name: Checkout repository uses: actions/checkout@v4 with: fetch-depth: 0 # Full history for better context - name: Run Claude Code Review id: claude uses: anthropics/claude-code-action@beta timeout-minutes: 15 with: claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} # Custom trigger phrase for review workflow trigger_phrase: "@claude-review" # Review-specific instructions custom_instructions: | You are performing a CODE REVIEW ONLY. You cannot make any changes to files. ## Your Role You are reviewing code for Archon V2 Beta, a local-first AI knowledge management system in early beta stage. ## Architecture Context - Frontend: React + TypeScript + Vite (port 3737) - Backend: FastAPI + Socket.IO + Python (port 8181) - MCP Service: MCP protocol server (port 8051) - Agents Service: PydanticAI agents (port 8052) - Database: Supabase (PostgreSQL + pgvector) ## Review Process 1. **Understand Changes** - For PR reviews: Check what files were changed and understand the context - For issue comments: Review the specific files or changes mentioned - Analyze the impact across all services (frontend, backend, MCP, agents) - Consider interactions between components ## Review Focus Areas ### 1. Code Quality - Backend (Python) - Type hints on all functions and classes - Pydantic v2 models for data validation (ConfigDict not class Config, model_dump() not dict()) - No print() statements (use logging instead) - Proper error handling with detailed error messages - Following PEP 8 - Google style docstrings where appropriate ### 2. Code Quality - Frontend (React/TypeScript) - Proper TypeScript types (avoid 'any') - React hooks used correctly - Component composition and reusability - Proper error boundaries - Following existing component patterns ### 3. Structure & Architecture - Each feature self-contained with its own models, service, and tools - Shared components only for things used by multiple features - Proper separation of concerns across services - API endpoints follow RESTful conventions ### 4. Testing - Unit tests co-located with code in tests/ folders - Edge cases covered - Mocking external dependencies - Frontend: Vitest tests for components - Backend: Pytest tests for services ### 5. Beta Project Principles (from CLAUDE.md) - No backwards compatibility needed - can break things - Fail fast with detailed errors (not graceful failures) - Remove dead code immediately - Focus on functionality over production patterns ## Required Output Format ## Summary [2-3 sentence overview of what the changes do and their impact] ## Previous Review Comments - [If this is a follow-up review, summarize unaddressed comments] - [If first review, state: "First review - no previous comments"] ## Issues Found Total: [X critical, Y important, Z minor] ### 🔴 Critical (Must Fix) [Issues that will break functionality or cause data loss] - **[Issue Title]** - `path/to/file.py:123` Problem: [What's wrong] Fix: [Specific solution] ### 🟡 Important (Should Fix) [Issues that impact user experience or code maintainability] - **[Issue Title]** - `path/to/file.tsx:45` Problem: [What's wrong] Fix: [Specific solution] ### 🟢 Minor (Consider) [Nice-to-have improvements] - **[Suggestion]** - `path/to/file.py:67` [Brief description and why it would help] ## Security Assessment Note: This is an early beta project without authentication. Security focus should be on: - Input validation to prevent crashes - SQL injection prevention - No hardcoded secrets or API keys - Proper CORS configuration [List any security issues found or state "No security issues found"] ## Performance Considerations - Database query efficiency (no N+1 queries) - Frontend bundle size impacts - Async/await usage in Python - React re-render optimization [List any performance issues or state "No performance concerns"] ## Good Practices Observed - [Highlight what was done well] - [Patterns that should be replicated] ## Questionable Practices - [Design decisions that might need reconsideration] - [Architectural concerns for discussion] ## Test Coverage **Current Coverage:** [Estimate based on what you see] **Missing Tests:** 1. **[Component/Function Name]** - What to test: [Specific functionality] - Why important: [Impact if it fails] - Suggested test: [One sentence description] 2. **[Component/Function Name]** - What to test: [Specific functionality] - Why important: [Impact if it fails] - Suggested test: [One sentence description] ## Recommendations **Merge Decision:** - [ ] Ready to merge as-is - [ ] Requires fixes before merging **Priority Actions:** 1. [Most important fix needed, if any] 2. [Second priority, if applicable] 3. ... **Rationale:** [Brief explanation rationale for above recommendations, considering this is an beta project focused on rapid iteration] --- *Review based on Archon V2 Beta guidelines and CLAUDE.md principles* # Commented out - using default tools # allowed_tools: "Read(*),Grep(*),LS(*),Glob(*),Bash(npm test*),Bash(npm run test*),Bash(npm run lint*),Bash(npm run type*),Bash(npm run check*),Bash(uv run pytest*),Bash(uv run ruff*),Bash(uv run mypy*),Bash(git log*),Bash(git diff*),Bash(git status*),Bash(git show*),Bash(cat *),Bash(head *),Bash(tail *),Bash(wc *),Bash(find * -type f),WebSearch(*),TodoWrite(*)" unauthorized-message: # Post message for unauthorized users if: | ( github.event_name == 'issue_comment' || github.event_name == 'pull_request_review_comment' ) && contains(github.event.comment.body, '@claude-review') && !contains(fromJSON('["Wirasm", "coleam00", "sean-eskerium"]'), github.event.comment.user.login) runs-on: ubuntu-latest permissions: issues: write pull-requests: write steps: - name: Post unauthorized message uses: actions/github-script@v7 with: script: | const comment = { owner: context.repo.owner, repo: context.repo.repo, body: `❌ @${context.actor} - You are not authorized to trigger Claude reviews.\n\nOnly the maintainers can trigger Claude: Please ask a maintainer for review.` }; if (context.eventName === 'issue_comment') { await github.rest.issues.createComment({ ...comment, issue_number: context.issue.number }); } else if (context.eventName === 'pull_request_review_comment') { await github.rest.pulls.createReplyForReviewComment({ owner: context.repo.owner, repo: context.repo.repo, pull_number: context.payload.pull_request.number, comment_id: context.payload.comment.id, body: comment.body }); } ================================================ FILE: .github/workflows/release-notes.yml ================================================ name: AI-Generated Release Notes on: workflow_dispatch: inputs: tag_name: description: 'Tag name (e.g., v1.0.0)' required: true type: string jobs: generate-release-notes: name: Generate Release Notes with Claude runs-on: ubuntu-latest permissions: contents: write pull-requests: read steps: - name: Checkout repository uses: actions/checkout@v4 with: fetch-depth: 0 # Full git history - name: Get release tag id: get_tag run: | if [ "${{ github.event_name }}" == "workflow_dispatch" ]; then echo "tag=${{ inputs.tag_name }}" >> $GITHUB_OUTPUT elif [ "${{ github.event_name }}" == "release" ]; then echo "tag=${{ github.event.release.tag_name }}" >> $GITHUB_OUTPUT else echo "tag=${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUT fi - name: Get previous tag id: prev_tag run: | CURRENT_TAG="${{ steps.get_tag.outputs.tag }}" PREVIOUS_TAG=$(git tag --sort=-v:refname | grep -A1 "^${CURRENT_TAG}$" | tail -1) if [ -z "$PREVIOUS_TAG" ] || [ "$PREVIOUS_TAG" == "$CURRENT_TAG" ]; then # First release or no previous tag - use initial commit PREVIOUS_TAG=$(git rev-list --max-parents=0 HEAD) echo "previous_tag=$PREVIOUS_TAG" >> $GITHUB_OUTPUT echo "is_first_release=true" >> $GITHUB_OUTPUT else echo "previous_tag=$PREVIOUS_TAG" >> $GITHUB_OUTPUT echo "is_first_release=false" >> $GITHUB_OUTPUT fi - name: Get commit messages id: commits run: | CURRENT_TAG="${{ steps.get_tag.outputs.tag }}" PREVIOUS_TAG="${{ steps.prev_tag.outputs.previous_tag }}" # Get commit history COMMITS=$(git log ${PREVIOUS_TAG}..${CURRENT_TAG} --pretty=format:"- %s (%h) by %an" --no-merges) # Save to file to preserve formatting echo "$COMMITS" > commits.txt # Get stats COMMIT_COUNT=$(echo "$COMMITS" | wc -l) echo "commit_count=$COMMIT_COUNT" >> $GITHUB_OUTPUT - name: Get changed files summary id: files run: | CURRENT_TAG="${{ steps.get_tag.outputs.tag }}" PREVIOUS_TAG="${{ steps.prev_tag.outputs.previous_tag }}" # Get file change statistics FILES_CHANGED=$(git diff ${PREVIOUS_TAG}..${CURRENT_TAG} --stat | tail -1) echo "files_summary=$FILES_CHANGED" >> $GITHUB_OUTPUT # Get detailed changes by component echo "### File Changes by Component" > changes.txt echo "" >> changes.txt echo "**Frontend:**" >> changes.txt git diff ${PREVIOUS_TAG}..${CURRENT_TAG} --stat -- archon-ui-main/ | head -20 >> changes.txt echo "" >> changes.txt echo "**Backend:**" >> changes.txt git diff ${PREVIOUS_TAG}..${CURRENT_TAG} --stat -- python/ | head -20 >> changes.txt echo "" >> changes.txt - name: Get closed PRs id: prs env: GH_TOKEN: ${{ github.token }} run: | CURRENT_TAG="${{ steps.get_tag.outputs.tag }}" PREVIOUS_TAG="${{ steps.prev_tag.outputs.previous_tag }}" # Get date of previous tag PREV_DATE=$(git log -1 --format=%ai ${PREVIOUS_TAG}) # Get merged PRs since previous tag gh pr list \ --state merged \ --limit 100 \ --json number,title,mergedAt,author,url \ --jq --arg date "$PREV_DATE" \ '.[] | select(.mergedAt >= $date) | "- #\(.number): \(.title) by @\(.author.login) - \(.url)"' \ > prs.txt || echo "No PRs found" > prs.txt - name: Prepare release notes context id: context run: | # Create a context file with all the information cat > release-context.md <<'EOF' # Release Notes Generation Task You are writing release notes for Archon V2 Beta, a local-first AI knowledge management system. ## Release Information **Version:** ${{ steps.get_tag.outputs.tag }} **Previous Version:** ${{ steps.prev_tag.outputs.previous_tag }} **Commits:** ${{ steps.commits.outputs.commit_count }} **Is First Release:** ${{ steps.prev_tag.outputs.is_first_release }} ## Commits ``` EOF cat commits.txt >> release-context.md cat >> release-context.md <<'EOF' ``` ## Pull Requests Merged ``` EOF cat prs.txt >> release-context.md cat >> release-context.md <<'EOF' ``` ## File Changes ``` EOF cat changes.txt >> release-context.md cat >> release-context.md <<'EOF' ``` ## Instructions Generate comprehensive release notes following this structure: # 🚀 Release ${{ steps.get_tag.outputs.tag }} ## 📝 Overview [2-3 sentence summary of this release] ## ✨ What's New ### Major Features - [List major new features with brief descriptions] ### Improvements - [List improvements and enhancements] ### Bug Fixes - [List bug fixes] ## 🔧 Technical Changes ### Backend (Python/FastAPI) - [Notable backend changes] ### Frontend (React/TypeScript) - [Notable frontend changes] ### Infrastructure - [Docker, CI/CD, deployment changes] ## 📊 Statistics - **Commits:** ${{ steps.commits.outputs.commit_count }} - **Pull Requests:** [Count from PRs list] - **Files Changed:** [From file stats] - **Contributors:** [Unique authors from commits] ## 🙏 Contributors Thanks to everyone who contributed to this release: [List unique contributors with @ mentions] ## ⚠️ Breaking Changes [List any breaking changes - this is beta software, so breaking changes are expected] ## 🔗 Links - **Full Changelog:** https://github.com/${{ github.repository }}/compare/${{ steps.prev_tag.outputs.previous_tag }}...${{ steps.get_tag.outputs.tag }} --- **Note:** This is a beta release. Features may change rapidly. Report issues at: https://github.com/${{ github.repository }}/issues --- Write in a professional yet enthusiastic tone. Focus on user-facing changes. Be specific but concise. IMPORTANT: Output ONLY the release notes in markdown format. Do not include any preamble, explanation, or commentary - just the release notes themselves starting with the header. EOF - name: Generate release notes with Claude Code id: claude uses: anthropics/claude-code-action@beta timeout-minutes: 10 with: claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} github_token: ${{ github.token }} mode: agent direct_prompt: | Read the file release-context.md which contains all the information about this release. Generate comprehensive release notes following the structure and instructions in that file. Output ONLY the release notes in markdown format - no preamble, no commentary, just the release notes. Write to a file called release_notes.md with the generated release notes. - name: Verify release notes were generated run: | if [ ! -f release_notes.md ]; then echo "❌ release_notes.md was not created" echo "Checking for any .md files in current directory:" ls -la *.md || echo "No .md files found" exit 1 fi if [ ! -s release_notes.md ]; then echo "❌ release_notes.md is empty" exit 1 fi echo "✅ Release notes generated successfully" echo "" echo "Preview (first 50 lines):" head -50 release_notes.md - name: Create or update GitHub release env: GH_TOKEN: ${{ github.token }} run: | TAG="${{ steps.get_tag.outputs.tag }}" # Check if release already exists if gh release view "$TAG" &>/dev/null; then echo "Release $TAG exists, updating notes..." gh release edit "$TAG" --notes-file release_notes.md else echo "Creating new release $TAG..." gh release create "$TAG" \ --title "Release $TAG" \ --notes-file release_notes.md \ --draft=false \ --latest fi - name: Upload release notes as artifact uses: actions/upload-artifact@v4 with: name: release-notes-${{ steps.get_tag.outputs.tag }} path: release_notes.md retention-days: 90 - name: Comment on related PRs if: steps.prev_tag.outputs.is_first_release == 'false' env: GH_TOKEN: ${{ github.token }} run: | TAG="${{ steps.get_tag.outputs.tag }}" # Get PR numbers from commits in this release CURRENT_TAG="${{ steps.get_tag.outputs.tag }}" PREVIOUS_TAG="${{ steps.prev_tag.outputs.previous_tag }}" # Extract PR numbers from commit messages PR_NUMBERS=$(git log ${PREVIOUS_TAG}..${CURRENT_TAG} --oneline | grep -oP '#\K\d+' || true) if [ -n "$PR_NUMBERS" ]; then for PR in $PR_NUMBERS; do echo "Adding release comment to PR #$PR" gh pr comment "$PR" \ --body "🎉 This pull request has been included in release [$TAG](https://github.com/${{ github.repository }}/releases/tag/$TAG)!" \ || echo "Could not comment on PR #$PR (might be closed)" done fi - name: Create summary if: always() run: | echo "# 🎉 Release Notes Generation Summary" >> $GITHUB_STEP_SUMMARY echo "" >> $GITHUB_STEP_SUMMARY echo "**Release Tag:** ${{ steps.get_tag.outputs.tag }}" >> $GITHUB_STEP_SUMMARY echo "**Previous Tag:** ${{ steps.prev_tag.outputs.previous_tag }}" >> $GITHUB_STEP_SUMMARY echo "**Commits:** ${{ steps.commits.outputs.commit_count }}" >> $GITHUB_STEP_SUMMARY echo "" >> $GITHUB_STEP_SUMMARY echo "## Generated Release Notes" >> $GITHUB_STEP_SUMMARY echo "" >> $GITHUB_STEP_SUMMARY if [ -f release_notes.md ]; then cat release_notes.md >> $GITHUB_STEP_SUMMARY else echo "⚠️ Release notes file not found" >> $GITHUB_STEP_SUMMARY fi ================================================ FILE: .gitignore ================================================ __pycache__ .env .serena .claude/settings.local.json PRPs/local PRPs/completed/ PRPs/stories/ PRPs/examples PRPs/features PRPs/specs PRPs/reviews/ /logs/ .zed tmp/ temp/ UAT/ # Temporary validation/report markdown files /*_RESULTS.md /*_SUMMARY.md /*_REPORT.md /*_SUCCESS.md /*_COMPLETION*.md /ACTUAL_*.md /VALIDATION_*.md .DS_Store # Local release notes testing release-notes-*.md ================================================ FILE: AGENTS.md ================================================ # CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## Beta Development Guidelines **Local-only deployment** - each user runs their own instance. ### Core Principles - **No backwards compatibility; we follow a fix‑forward approach** — remove deprecated code immediately - **Detailed errors over graceful failures** - we want to identify and fix issues fast - **Break things to improve them** - beta is for rapid iteration - **Continuous improvement** - embrace change and learn from mistakes - **KISS** - keep it simple - **DRY** when appropriate - **YAGNI** — don't implement features that are not needed ### Error Handling **Core Principle**: In beta, we need to intelligently decide when to fail hard and fast to quickly address issues, and when to allow processes to complete in critical services despite failures. Read below carefully and make intelligent decisions on a case-by-case basis. #### When to Fail Fast and Loud (Let it Crash!) These errors should stop execution and bubble up immediately: (except for crawling flows) - **Service startup failures** - If credentials, database, or any service can't initialize, the system should crash with a clear error - **Missing configuration** - Missing environment variables or invalid settings should stop the system - **Database connection failures** - Don't hide connection issues, expose them - **Authentication/authorization failures** - Security errors must be visible and halt the operation - **Data corruption or validation errors** - Never silently accept bad data, Pydantic should raise - **Critical dependencies unavailable** - If a required service is down, fail immediately - **Invalid data that would corrupt state** - Never store zero embeddings, null foreign keys, or malformed JSON #### When to Complete but Log Detailed Errors These operations should continue but track and report failures clearly: - **Batch processing** - When crawling websites or processing documents, complete what you can and report detailed failures for each item - **Background tasks** - Embedding generation, async jobs should finish the queue but log failures - **WebSocket events** - Don't crash on a single event failure, log it and continue serving other clients - **Optional features** - If projects/tasks are disabled, log and skip rather than crash - **External API calls** - Retry with exponential backoff, then fail with a clear message about what service failed and why #### Critical Nuance: Never Accept Corrupted Data When a process should continue despite failures, it must **skip the failed item entirely** rather than storing corrupted data #### Error Message Guidelines - Include context about what was being attempted when the error occurred - Preserve full stack traces with `exc_info=True` in Python logging - Use specific exception types, not generic Exception catching - Include relevant IDs, URLs, or data that helps debug the issue - Never return None/null to indicate failure - raise an exception with details - For batch operations, always report both success count and detailed failure list ### Code Quality - Remove dead code immediately rather than maintaining it - no backward compatibility or legacy functions - Avoid backward compatibility mappings or legacy function wrappers - Fix forward - Focus on user experience and feature completeness - When updating code, don't reference what is changing (avoid keywords like SIMPLIFIED, ENHANCED, LEGACY, CHANGED, REMOVED), instead focus on comments that document just the functionality of the code - When commenting on code in the codebase, only comment on the functionality and reasoning behind the code. Refrain from speaking to Archon being in "beta" or referencing anything else that comes from these global rules. ## Development Commands ### Frontend (archon-ui-main/) ```bash npm run dev # Start development server on port 3737 npm run build # Build for production npm run lint # Run ESLint on legacy code (excludes /features) npm run lint:files path/to/file.tsx # Lint specific files # Biome for /src/features directory only npm run biome # Check features directory npm run biome:fix # Auto-fix issues npm run biome:format # Format code (120 char lines) npm run biome:ai # Machine-readable JSON output for AI npm run biome:ai-fix # Auto-fix with JSON output # Testing npm run test # Run all tests in watch mode npm run test:ui # Run with Vitest UI interface npm run test:coverage:stream # Run once with streaming output vitest run src/features/projects # Test specific directory # TypeScript npx tsc --noEmit # Check all TypeScript errors npx tsc --noEmit 2>&1 | grep "src/features" # Check features only ``` ### Backend (python/) ```bash # Using uv package manager (preferred) uv sync --group all # Install all dependencies uv run python -m src.server.main # Run server locally on 8181 uv run pytest # Run all tests uv run pytest tests/test_api_essentials.py -v # Run specific test uv run ruff check # Run linter uv run ruff check --fix # Auto-fix linting issues uv run mypy src/ # Type check # Docker operations docker compose up --build -d # Start all services docker compose --profile backend up -d # Backend only (for hybrid dev) docker compose logs -f archon-server # View server logs docker compose logs -f archon-mcp # View MCP server logs docker compose restart archon-server # Restart after code changes docker compose down # Stop all services docker compose down -v # Stop and remove volumes ``` ### Quick Workflows ```bash # Hybrid development (recommended) - backend in Docker, frontend local make dev # Or manually: docker compose --profile backend up -d && cd archon-ui-main && npm run dev # Full Docker mode make dev-docker # Or: docker compose up --build -d # Run linters before committing make lint # Runs both frontend and backend linters make lint-fe # Frontend only (ESLint + Biome) make lint-be # Backend only (Ruff + MyPy) # Testing make test # Run all tests make test-fe # Frontend tests only make test-be # Backend tests only ``` ## Architecture Overview @PRPs/ai_docs/ARCHITECTURE.md #### TanStack Query Implementation For architecture and file references: @PRPs/ai_docs/DATA_FETCHING_ARCHITECTURE.md For code patterns and examples: @PRPs/ai_docs/QUERY_PATTERNS.md #### Service Layer Pattern See implementation examples: - API routes: `python/src/server/api_routes/projects_api.py` - Service layer: `python/src/server/services/project_service.py` - Pattern: API Route → Service → Database #### Error Handling Patterns See implementation examples: - Custom exceptions: `python/src/server/exceptions.py` - Exception handlers: `python/src/server/main.py` (search for @app.exception_handler) - Service error handling: `python/src/server/services/` (various services) ## ETag Implementation @PRPs/ai_docs/ETAG_IMPLEMENTATION.md ## Database Schema Key tables in Supabase: - `sources` - Crawled websites and uploaded documents - Stores metadata, crawl status, and configuration - `documents` - Processed document chunks with embeddings - Text chunks with vector embeddings for semantic search - `projects` - Project management (optional feature) - Contains features array, documents, and metadata - `tasks` - Task tracking linked to projects - Status: todo, doing, review, done - Assignee: User, Archon, AI IDE Agent - `code_examples` - Extracted code snippets - Language, summary, and relevance metadata ## API Naming Conventions @PRPs/ai_docs/API_NAMING_CONVENTIONS.md Use database values directly (no mapping in the FE typesafe from BE and up): ## Environment Variables Required in `.env`: ```bash SUPABASE_URL=https://your-project.supabase.co # Or http://host.docker.internal:8000 for local SUPABASE_SERVICE_KEY=your-service-key-here # Use legacy key format for cloud Supabase ``` Optional variables and full configuration: See `python/.env.example` for complete list ## Common Development Tasks ### Add a new API endpoint 1. Create route handler in `python/src/server/api_routes/` 2. Add service logic in `python/src/server/services/` 3. Include router in `python/src/server/main.py` 4. Update frontend service in `archon-ui-main/src/features/[feature]/services/` ### Add a new UI component in features directory 1. Use Radix UI primitives from `src/features/ui/primitives/` 2. Create component in relevant feature folder under `src/features/[feature]/components/` 3. Define types in `src/features/[feature]/types/` 4. Use TanStack Query hook from `src/features/[feature]/hooks/` 5. Apply Tron-inspired glassmorphism styling with Tailwind ### Add or modify MCP tools 1. MCP tools are in `python/src/mcp_server/features/[feature]/[feature]_tools.py` 2. Follow the pattern: - `find_[resource]` - Handles list, search, and get single item operations - `manage_[resource]` - Handles create, update, delete with an "action" parameter 3. Register tools in the feature's `__init__.py` file ### Debug MCP connection issues 1. Check MCP health: `curl http://localhost:8051/health` 2. View MCP logs: `docker compose logs archon-mcp` 3. Test tool execution via UI MCP page 4. Verify Supabase connection and credentials ### Fix TypeScript/Linting Issues ```bash # TypeScript errors in features npx tsc --noEmit 2>&1 | grep "src/features" # Biome auto-fix for features npm run biome:fix # ESLint for legacy code npm run lint:files src/components/SomeComponent.tsx ``` ## Code Quality Standards ### Frontend - **TypeScript**: Strict mode enabled, no implicit any - **Biome** for `/src/features/`: 120 char lines, double quotes, trailing commas - **ESLint** for legacy code: Standard React rules - **Testing**: Vitest with React Testing Library ### Backend - **Python 3.12** with 120 character line length - **Ruff** for linting - checks for errors, warnings, unused imports - **Mypy** for type checking - ensures type safety - **Pytest** for testing with async support ## MCP Tools Available When connected to Claude/Cursor/Windsurf, the following tools are available: ### Knowledge Base Tools - `archon:rag_search_knowledge_base` - Search knowledge base for relevant content - `archon:rag_search_code_examples` - Find code snippets in the knowledge base - `archon:rag_get_available_sources` - List available knowledge sources ### Project Management - `archon:find_projects` - Find all projects, search, or get specific project (by project_id) - `archon:manage_project` - Manage projects with actions: "create", "update", "delete" ### Task Management - `archon:find_tasks` - Find tasks with search, filters, or get specific task (by task_id) - `archon:manage_task` - Manage tasks with actions: "create", "update", "delete" ### Document Management - `archon:find_documents` - Find documents, search, or get specific document (by document_id) - `archon:manage_document` - Manage documents with actions: "create", "update", "delete" ### Version Control - `archon:find_versions` - Find version history or get specific version - `archon:manage_version` - Manage versions with actions: "create", "restore" ## Important Notes - Projects feature is optional - toggle in Settings UI - HTTP polling handles all updates - Frontend uses Vite proxy for API calls in development - Python backend uses `uv` for dependency management - Docker Compose handles service orchestration - TanStack Query for all data fetching - NO PROP DRILLING - Vertical slice architecture in `/features` - features own their sub-features ================================================ FILE: CLAUDE.md ================================================ # CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## Beta Development Guidelines **Local-only deployment** - each user runs their own instance. ### Core Principles - **No backwards compatibility; we follow a fix‑forward approach** — remove deprecated code immediately - **Detailed errors over graceful failures** - we want to identify and fix issues fast - **Break things to improve them** - beta is for rapid iteration - **Continuous improvement** - embrace change and learn from mistakes - **KISS** - keep it simple - **DRY** when appropriate - **YAGNI** — don't implement features that are not needed ### Error Handling **Core Principle**: In beta, we need to intelligently decide when to fail hard and fast to quickly address issues, and when to allow processes to complete in critical services despite failures. Read below carefully and make intelligent decisions on a case-by-case basis. #### When to Fail Fast and Loud (Let it Crash!) These errors should stop execution and bubble up immediately: (except for crawling flows) - **Service startup failures** - If credentials, database, or any service can't initialize, the system should crash with a clear error - **Missing configuration** - Missing environment variables or invalid settings should stop the system - **Database connection failures** - Don't hide connection issues, expose them - **Authentication/authorization failures** - Security errors must be visible and halt the operation - **Data corruption or validation errors** - Never silently accept bad data, Pydantic should raise - **Critical dependencies unavailable** - If a required service is down, fail immediately - **Invalid data that would corrupt state** - Never store zero embeddings, null foreign keys, or malformed JSON #### When to Complete but Log Detailed Errors These operations should continue but track and report failures clearly: - **Batch processing** - When crawling websites or processing documents, complete what you can and report detailed failures for each item - **Background tasks** - Embedding generation, async jobs should finish the queue but log failures - **WebSocket events** - Don't crash on a single event failure, log it and continue serving other clients - **Optional features** - If projects/tasks are disabled, log and skip rather than crash - **External API calls** - Retry with exponential backoff, then fail with a clear message about what service failed and why #### Critical Nuance: Never Accept Corrupted Data When a process should continue despite failures, it must **skip the failed item entirely** rather than storing corrupted data #### Error Message Guidelines - Include context about what was being attempted when the error occurred - Preserve full stack traces with `exc_info=True` in Python logging - Use specific exception types, not generic Exception catching - Include relevant IDs, URLs, or data that helps debug the issue - Never return None/null to indicate failure - raise an exception with details - For batch operations, always report both success count and detailed failure list ### Code Quality - Remove dead code immediately rather than maintaining it - no backward compatibility or legacy functions - Avoid backward compatibility mappings or legacy function wrappers - Fix forward - Focus on user experience and feature completeness - When updating code, don't reference what is changing (avoid keywords like SIMPLIFIED, ENHANCED, LEGACY, CHANGED, REMOVED), instead focus on comments that document just the functionality of the code - When commenting on code in the codebase, only comment on the functionality and reasoning behind the code. Refrain from speaking to Archon being in "beta" or referencing anything else that comes from these global rules. ## Development Commands ### Frontend (archon-ui-main/) ```bash npm run dev # Start development server on port 3737 npm run build # Build for production npm run lint # Run ESLint on legacy code (excludes /features) npm run lint:files path/to/file.tsx # Lint specific files # Biome for /src/features directory only npm run biome # Check features directory npm run biome:fix # Auto-fix issues npm run biome:format # Format code (120 char lines) npm run biome:ai # Machine-readable JSON output for AI npm run biome:ai-fix # Auto-fix with JSON output # Testing npm run test # Run all tests in watch mode npm run test:ui # Run with Vitest UI interface npm run test:coverage:stream # Run once with streaming output vitest run src/features/projects # Test specific directory # TypeScript npx tsc --noEmit # Check all TypeScript errors npx tsc --noEmit 2>&1 | grep "src/features" # Check features only ``` ### Backend (python/) ```bash # Using uv package manager (preferred) uv sync --group all # Install all dependencies uv run python -m src.server.main # Run server locally on 8181 uv run pytest # Run all tests uv run pytest tests/test_api_essentials.py -v # Run specific test uv run ruff check # Run linter uv run ruff check --fix # Auto-fix linting issues uv run mypy src/ # Type check # Agent Work Orders Service (independent microservice) make agent-work-orders # Run agent work orders service locally on 8053 # Or manually: uv run python -m uvicorn src.agent_work_orders.server:app --port 8053 --reload # Docker operations docker compose up --build -d # Start all services docker compose --profile backend up -d # Backend only (for hybrid dev) docker compose --profile work-orders up -d # Include agent work orders service docker compose logs -f archon-server # View server logs docker compose logs -f archon-mcp # View MCP server logs docker compose logs -f archon-agent-work-orders # View agent work orders service logs docker compose restart archon-server # Restart after code changes docker compose down # Stop all services docker compose down -v # Stop and remove volumes ``` ### Quick Workflows ```bash # Hybrid development (recommended) - backend in Docker, frontend local make dev # Or manually: docker compose --profile backend up -d && cd archon-ui-main && npm run dev # Hybrid with Agent Work Orders Service - backend in Docker, agent work orders local make dev-work-orders # Starts backend in Docker, prompts to run agent service in separate terminal # Then in separate terminal: make agent-work-orders # Start agent work orders service locally # Full Docker mode make dev-docker # Or: docker compose up --build -d docker compose --profile work-orders up -d # Include agent work orders service # All Local (3 terminals) - for agent work orders service development # Terminal 1: uv run python -m uvicorn src.server.main:app --port 8181 --reload # Terminal 2: make agent-work-orders # Terminal 3: cd archon-ui-main && npm run dev # Run linters before committing make lint # Runs both frontend and backend linters make lint-fe # Frontend only (ESLint + Biome) make lint-be # Backend only (Ruff + MyPy) # Testing make test # Run all tests make test-fe # Frontend tests only make test-be # Backend tests only ``` ## Architecture Overview @PRPs/ai_docs/ARCHITECTURE.md #### TanStack Query Implementation For architecture and file references: @PRPs/ai_docs/DATA_FETCHING_ARCHITECTURE.md For code patterns and examples: @PRPs/ai_docs/QUERY_PATTERNS.md #### Service Layer Pattern See implementation examples: - API routes: `python/src/server/api_routes/projects_api.py` - Service layer: `python/src/server/services/project_service.py` - Pattern: API Route → Service → Database #### Error Handling Patterns See implementation examples: - Custom exceptions: `python/src/server/exceptions.py` - Exception handlers: `python/src/server/main.py` (search for @app.exception_handler) - Service error handling: `python/src/server/services/` (various services) ## ETag Implementation @PRPs/ai_docs/ETAG_IMPLEMENTATION.md ## Database Schema Key tables in Supabase: - `sources` - Crawled websites and uploaded documents - Stores metadata, crawl status, and configuration - `documents` - Processed document chunks with embeddings - Text chunks with vector embeddings for semantic search - `projects` - Project management (optional feature) - Contains features array, documents, and metadata - `tasks` - Task tracking linked to projects - Status: todo, doing, review, done - Assignee: User, Archon, AI IDE Agent - `code_examples` - Extracted code snippets - Language, summary, and relevance metadata ## API Naming Conventions @PRPs/ai_docs/API_NAMING_CONVENTIONS.md Use database values directly (no FE mapping; type‑safe end‑to‑end from BE upward): ## Environment Variables Required in `.env`: ```bash SUPABASE_URL=https://your-project.supabase.co # Or http://host.docker.internal:8000 for local SUPABASE_SERVICE_KEY=your-service-key-here # Use legacy key format for cloud Supabase ``` Optional variables and full configuration: See `python/.env.example` for complete list ### Repository Configuration Repository information (owner, name) is centralized in `python/src/server/config/version.py`: - `GITHUB_REPO_OWNER` - GitHub repository owner (default: "coleam00") - `GITHUB_REPO_NAME` - GitHub repository name (default: "Archon") This is the single source of truth for repository configuration. All services (version checking, bug reports, etc.) should import these constants rather than hardcoding repository URLs. Environment variable override: `GITHUB_REPO="owner/repo"` can be set to override defaults. ## Common Development Tasks ### Add a new API endpoint 1. Create route handler in `python/src/server/api_routes/` 2. Add service logic in `python/src/server/services/` 3. Include router in `python/src/server/main.py` 4. Update frontend service in `archon-ui-main/src/features/[feature]/services/` ### Add a new UI component in features directory **IMPORTANT**: Review UI design standards in `@PRPs/ai_docs/UI_STANDARDS.md` before creating UI components. 1. Use Radix UI primitives from `src/features/ui/primitives/` 2. Create component in relevant feature folder under `src/features/[feature]/components/` 3. Define types in `src/features/[feature]/types/` 4. Use TanStack Query hook from `src/features/[feature]/hooks/` 5. Apply Tron-inspired glassmorphism styling with Tailwind 6. Follow responsive design patterns (mobile-first with breakpoints) 7. Ensure no dynamic Tailwind class construction (see UI_STANDARDS.md Section 2) ### Add or modify MCP tools 1. MCP tools are in `python/src/mcp_server/features/[feature]/[feature]_tools.py` 2. Follow the pattern: - `find_[resource]` - Handles list, search, and get single item operations - `manage_[resource]` - Handles create, update, delete with an "action" parameter 3. Register tools in the feature's `__init__.py` file ### Debug MCP connection issues 1. Check MCP health: `curl http://localhost:8051/health` 2. View MCP logs: `docker compose logs archon-mcp` 3. Test tool execution via UI MCP page 4. Verify Supabase connection and credentials ### Fix TypeScript/Linting Issues ```bash # TypeScript errors in features npx tsc --noEmit 2>&1 | grep "src/features" # Biome auto-fix for features npm run biome:fix # ESLint for legacy code npm run lint:files src/components/SomeComponent.tsx ``` ## Code Quality Standards ### Frontend - **TypeScript**: Strict mode enabled, no implicit any - **Biome** for `/src/features/`: 120 char lines, double quotes, trailing commas - **ESLint** for legacy code: Standard React rules - **Testing**: Vitest with React Testing Library ### Backend - **Python 3.12** with 120 character line length - **Ruff** for linting - checks for errors, warnings, unused imports - **Mypy** for type checking - ensures type safety - **Pytest** for testing with async support ## MCP Tools Available When connected to Claude/Cursor/Windsurf, the following tools are available: ### Knowledge Base Tools - `archon:rag_search_knowledge_base` - Search knowledge base for relevant content - `archon:rag_search_code_examples` - Find code snippets in the knowledge base - `archon:rag_get_available_sources` - List available knowledge sources - `archon:rag_list_pages_for_source` - List all pages for a given source (browse documentation structure) - `archon:rag_read_full_page` - Retrieve full page content by page_id or URL ### Project Management - `archon:find_projects` - Find all projects, search, or get specific project (by project_id) - `archon:manage_project` - Manage projects with actions: "create", "update", "delete" ### Task Management - `archon:find_tasks` - Find tasks with search, filters, or get specific task (by task_id) - `archon:manage_task` - Manage tasks with actions: "create", "update", "delete" ### Document Management - `archon:find_documents` - Find documents, search, or get specific document (by document_id) - `archon:manage_document` - Manage documents with actions: "create", "update", "delete" ### Version Control - `archon:find_versions` - Find version history or get specific version - `archon:manage_version` - Manage versions with actions: "create", "restore" ## Important Notes - Projects feature is optional - toggle in Settings UI - TanStack Query handles all data fetching; smart HTTP polling is used where appropriate (no WebSockets) - Frontend uses Vite proxy for API calls in development - Python backend uses `uv` for dependency management - Docker Compose handles service orchestration - TanStack Query for all data fetching - NO PROP DRILLING - Vertical slice architecture in `/features` - features own their sub-features ================================================ FILE: CONTRIBUTING.md ================================================ # Contributing to Archon Help us build the definitive knowledge and task management engine for AI coding assistants! This guide shows you how to contribute new features, bug fixes, and improvements to the Archon platform. ## 🎯 What is Archon? Archon is a **microservices-based engine** that provides AI coding assistants with access to your documentation, project knowledge, and task management through the Model Context Protocol (MCP). The platform consists of four main services that work together to deliver comprehensive knowledge management and project automation. ## 🏗️ Architecture Overview ### Microservices Structure Archon uses true microservices architecture with clear separation of concerns: ``` ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ Frontend UI │ │ Server (API) │ │ MCP Server │ │ Agents Service │ │ │ │ │ │ │ │ │ │ React + Vite │◄──►│ FastAPI + │◄──►│ Lightweight │◄──►│ PydanticAI │ │ Port 3737 │ │ SocketIO │ │ HTTP Wrapper │ │ Port 8052 │ │ │ │ Port 8181 │ │ Port 8051 │ │ │ └─────────────────┘ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ │ │ │ └────────────────────────┼────────────────────────┼────────────────────────┘ │ │ ┌─────────────────┐ │ │ Database │ │ │ │ │ │ Supabase │◄──────────────┘ │ PostgreSQL │ │ PGVector │ └─────────────────┘ ``` ### Service Responsibilities | Service | Location | Purpose | Key Features | | -------------- | -------------------- | ---------------------------- | -------------------------------------------------------------------------- | | **Frontend** | `archon-ui-main/` | Web interface and dashboard | React, TypeScript, TailwindCSS, Socket.IO client | | **Server** | `python/src/server/` | Core business logic and APIs | FastAPI, service layer, Socket.IO broadcasts, all LLM/embedding operations | | **MCP Server** | `python/src/mcp/` | MCP protocol interface | Lightweight HTTP wrapper, 14 MCP tools, session management | | **Agents** | `python/src/agents/` | PydanticAI agent hosting | Document and RAG agents, streaming responses | ### Communication Patterns - **HTTP-based**: All inter-service communication uses HTTP APIs - **Socket.IO**: Real-time updates from Server to Frontend - **MCP Protocol**: AI clients connect to MCP Server via SSE or stdio - **No Direct Imports**: Services are truly independent with no shared code dependencies ## 🚀 Quick Start for Contributors ### Prerequisites - [Docker Desktop](https://www.docker.com/products/docker-desktop/) - [Node.js 18+](https://nodejs.org/) (for hybrid development mode) - [Supabase](https://supabase.com/) account (free tier works) - [OpenAI API key](https://platform.openai.com/api-keys) or alternative LLM provider - (Optional) [Make](https://www.gnu.org/software/make/) for simplified workflows - Basic knowledge of Python (FastAPI) and TypeScript (React) ### Initial Setup After forking the repository, you'll need to: 1. **Environment Configuration** ```bash cp .env.example .env # Edit .env with your Supabase credentials ``` 2. **Database Setup** - Run `migration/complete_setup.sql` in your Supabase SQL Editor 3. **Start Development Environment** ```bash # Using Docker Compose directly docker compose --profile full up --build -d # Or using Make (if installed) make dev-docker ``` 4. **Configure API Keys** - Open http://localhost:3737 - Go to Settings → Add your OpenAI API key ## 👑 Important Standards for Contributing There are a few very important rules that we ask you follow when contributing to Archon. Some things like testing are covered more later in this document but there are a few very important specifics to call out here. **1. Check the list of PRs** to make sure you aren't about to fix or implement something that's already been done! Also be sure to check the [Archon Kanban board](https://github.com/users/coleam00/projects/1) where the maintainers are manage issues/features. **2. Try to keep the changes to less than 2,000 lines of code.** The more granular the PR, the better! If your changes must be larger, it's very important to go into extra detail in your PR and explain why the larger changes are necessary. **3. Keep PRs to a single feature.** Please split any that implement multiple features into multiple PRs. **4. Even within individual features, aim for simplicity** - concise implementations are always the best! **5. If your code changes touch the crawling functionality in any way**, please test crawling an llms-full.txt, llms.txt, a sitemap.xml, and a normal URL with recursive crawling. Here are smaller examples you can use for testing: - llms.txt: https://docs.mem0.ai/llms.txt - llms-full.txt: https://docs.mem0.ai/llms-full.txt - sitemap.xml: https://mem0.ai/sitemap.xml - Normal URL: https://docs.anthropic.com/en/docs/claude-code/overview Make sure the crawling completes end to end, the code examples exist, and the Archon MCP can be used to successfully search through the documentation. **6. If your code changes touch the project/task management in any way**, please test all the CRUD (Create, Read, Update, Delete) operations on both projects and tasks. Generally you will: - Create a new project - Create a couple of tasks - Move the tasks around the kanban board - Edit descriptions Test these things using both the UI and the MCP server. This process will be similar if your code changes touch the docs part of Archon too. **7. If your code changes touch the MCP server instructions or anything else more high level** that could affect how AI coding assistants use the Archon MCP, please retest by creating a simple project from scratch that leverages Archon for RAG, task management, etc. ## 🔄 Contribution Process ### 1. Choose Your Contribution **Bug Fixes:** - Check existing issues for reported bugs - Create detailed reproduction steps - Fix in smallest possible scope **New Features:** - Optional: Open an issue first to discuss the feature - Get feedback on approach and architecture (from maintainers and/or AI coding assistants) - Break large features into smaller PRs **Documentation:** - Look for gaps in current documentation - Focus on user-facing improvements - Update both code docs and user guides ### 2. Development Process 1. **Fork the Repository** - Go to https://github.com/coleam00/archon - Click the "Fork" button in the top right corner - This creates your own copy of the repository ```bash # Clone your fork from main branch for contributing (replace 'your-username' with your GitHub username) git clone https://github.com/your-username/archon.git cd archon # Add upstream remote to sync with main repository later git remote add upstream https://github.com/coleam00/archon.git ``` **Note:** The `main` branch is used for contributions and contains the latest development work. The `stable` branch is for users who want a more tested, stable version of Archon. 2. **🤖 AI Coding Assistant Setup** **IMPORTANT**: If you're using AI coding assistants to help contribute to Archon, set up our global rules for optimal results. - **Claude Code**: ✅ Already configured! The `CLAUDE.md` file is automatically used - **Cursor**: Copy `CLAUDE.md` content to a new `.cursorrules` file in the project root - **Windsurf**: Copy `CLAUDE.md` content to a new `.windsurfrules` file in the project root - **Other assistants**: Copy `CLAUDE.md` content to your assistant's global rules/context file These rules contain essential context about Archon's architecture, service patterns, MCP implementation, and development best practices. Using them will help your AI assistant follow our conventions and implement features correctly. 3. **Create Feature Branch** **Best Practice**: Always create a feature branch from main rather than working directly on it. This keeps your main branch clean and makes it easier to sync with the upstream repository. ```bash git checkout -b feature/your-feature-name # or git checkout -b fix/bug-description ``` 4. **Make Your Changes** - Follow the service architecture patterns - Add tests for new functionality - Update documentation as needed 5. **Verify Your Changes** - Run full test suite - Test manually via Docker environment - Verify no regressions in existing features ### 3. Submit Pull Request 1. **Push to Your Fork** ```bash # First time pushing this branch git push -u origin feature/your-feature-name # For subsequent pushes to the same branch git push ``` 2. **Create Pull Request via GitHub UI** - Go to your fork on GitHub (https://github.com/your-username/archon) - Click "Contribute" then "Open pull request" - GitHub will automatically detect your branch and show a comparison - The PR template will be automatically filled in the description - Review the template and fill out the required sections - Click "Create pull request" 3. **Testing Requirements** **Before submitting, ensure:** - [ ] All existing tests pass - [ ] New tests added for new functionality - [ ] Manual testing of affected user flows - [ ] Docker builds succeed for all services **Test commands:** ```bash # Using Make (if installed) make test # Run all tests make test-fe # Frontend tests only make test-be # Backend tests only # Or manually cd python && python -m pytest # Backend tests cd archon-ui-main && npm run test # Frontend tests # Full integration test docker compose --profile full up --build -d # Test via UI at http://localhost:3737 ``` 4. **Review Process** - Automated tests will run on your PR - Maintainers will review code and architecture - Address feedback and iterate as needed ## 📋 Contribution Areas ### 🔧 Backend Services (Python) **When to contribute:** - Adding new API endpoints or business logic - Implementing new MCP tools - Creating new service classes or utilities - Improving crawling, embedding, or search functionality (everything for RAG) **Key locations:** - **Service Layer**: `python/src/server/services/` - Core business logic organized by domain - **API Endpoints**: `python/src/server/api_routes/` - REST API route handlers - **MCP Tools**: `python/src/mcp/modules/` - MCP protocol implementations - **Agents**: `python/src/agents/` - PydanticAI agent implementations **Development patterns:** - Services use dependency injection with `supabase_client` parameter - Use async/await for I/O operations, sync for pure logic - Follow service → API → MCP layer separation ### 🎨 Frontend (React/TypeScript) **When to contribute:** - Adding new UI components or pages - Implementing real-time features with Socket.IO - Creating new service integrations - Improving user experience and accessibility **Key locations:** - **Components**: `archon-ui-main/src/components/` - Reusable UI components organized by feature - **Pages**: `archon-ui-main/src/pages/` - Main application routes - **Services**: `archon-ui-main/src/services/` - API communication and business logic - **Contexts**: `archon-ui-main/src/contexts/` - React context providers for global state **Development patterns:** - Context-based state management (no Redux) - Service layer abstraction for API calls - Socket.IO for real-time updates - TailwindCSS for styling with custom design system ### 🐳 Infrastructure (Docker/DevOps) **When to contribute:** - Optimizing container builds or sizes - Improving service orchestration - Adding new environment configurations - Enhancing health checks and monitoring **Key locations:** - **Docker**: `python/Dockerfile.*` - Service-specific containers - **Compose**: `docker-compose.yml` - Service orchestration - **Config**: `.env.example` - Environment variable documentation ### 📚 Documentation **When to contribute:** - Adding API documentation - Creating deployment guides - Writing feature tutorials - Improving architecture explanations **Key locations:** - **Docs Site**: `docs/docs/` - Docusaurus-based documentation - **API Docs**: Auto-generated from FastAPI endpoints - **README**: Main project documentation ## 🛠️ Development Workflows ### Backend Development (Python) 1. **Adding a New Service** ```bash # Create service class in appropriate domain python/src/server/services/your_domain/your_service.py # Add API endpoints python/src/server/api_routes/your_api.py # Optional: Add MCP tools python/src/mcp/modules/your_module.py ``` 2. **Testing Your Changes** ```bash # Using Make (if installed) make test-be # Or manually cd python && python -m pytest tests/ # Run specific test categories python -m pytest -m unit # Unit tests only python -m pytest -m integration # Integration tests only ``` 3. **Code Quality** ```bash # Follow service patterns from existing code # Maintain consistency with the codebase ``` ### Frontend Development (React) 1. **Adding a New Component** ```bash # Create in appropriate category archon-ui-main/src/components/your-category/YourComponent.tsx # Add to appropriate page or parent component archon-ui-main/src/pages/YourPage.tsx ``` 2. **UI Design Standards** Before creating or modifying UI components, review the design standards: - **UI Standards**: `PRPs/ai_docs/UI_STANDARDS.md` - Complete Tailwind v4, Radix, and responsive design patterns - **Style Guide**: Enable in Settings → scroll to "Feature Flags" → Enable "Style Guide Page" - Access at http://localhost:3737/style-guide - View all available primitives, colors, layouts, and component patterns - **UI Consistency Review**: Run `/archon:archon-ui-consistency-review ` to automatically check your components for compliance 3. **Testing Your Changes** ```bash # Using Make (if installed) make test-fe # Or manually cd archon-ui-main && npm run test # Run with coverage npm run test:coverage # Run in UI mode npm run test:ui ``` 4. **Development Server** ```bash # Using Make for hybrid mode (if installed) make dev # Backend in Docker, frontend local # Or manually for faster iteration cd archon-ui-main && npm run dev # Still connects to Docker backend services ``` ## ✅ Quality Standards ### Code Requirements 1. **Backend (Python)** - Follow existing service patterns and dependency injection - Use type hints and proper async/await patterns - Include unit tests for new business logic - Update API documentation if adding endpoints 2. **Frontend (TypeScript)** - Use TypeScript with proper typing - Follow existing component patterns and context usage - Include component tests for new UI features - Ensure responsive design and accessibility 3. **Documentation** - Update relevant docs for user-facing changes - Include inline code documentation for complex logic - Add migration notes for breaking changes ### Performance Considerations - **Service Layer**: Keep business logic efficient, use async for I/O - **API Responses**: Consider pagination for large datasets - **Real-time Updates**: Use Socket.IO rooms appropriately - **Database**: Consider indexes for new query patterns ## 🏛️ Architectural Guidelines ### Service Design Principles 1. **Single Responsibility**: Each service has a focused purpose 2. **HTTP Communication**: No direct imports between services 3. **Database Centralization**: Supabase as single source of truth 4. **Real-time Updates**: Socket.IO for live collaboration features ### Adding New MCP Tools **Tool Pattern:** ```python @mcp.tool() async def your_new_tool(ctx: Context, param: str) -> str: """ Tool description for AI clients. Args: param: Description of parameter Returns: JSON string with results """ async with httpx.AsyncClient() as client: response = await client.post(f"{API_URL}/api/your-endpoint", json={"param": param}) return response.json() ``` ### Adding New Service Classes **Service Pattern:** ```python class YourService: def __init__(self, supabase_client=None): self.supabase_client = supabase_client or get_supabase_client() def your_operation(self, param: str) -> Tuple[bool, Dict[str, Any]]: try: # Business logic here result = self.supabase_client.table("table").insert(data).execute() return True, {"data": result.data} except Exception as e: logger.error(f"Error in operation: {e}") return False, {"error": str(e)} ``` ## 🤝 Community Standards ### Communication Guidelines - **Be Constructive**: Focus on improving the codebase and user experience - **Be Specific**: Provide detailed examples and reproduction steps - **Be Collaborative**: Welcome diverse perspectives and approaches - **Be Patient**: Allow time for review and discussion ### Code Review Process **As a Contributor:** - Write clear PR descriptions - Respond promptly to review feedback - Test your changes thoroughly **As a Reviewer:** - Focus on architecture, correctness, and user impact - Provide specific, actionable feedback - Acknowledge good practices and improvements ## 📞 Getting Help - **GitHub Issues**: For bugs, feature requests, and questions - **Architecture Questions**: Use the GitHub discussions ## 🎖️ Recognition Contributors receive: - **Attribution**: Recognition in release notes and documentation - **Maintainer Track**: Path to maintainer role for consistent contributors - **Community Impact**: Help improve AI development workflows for thousands of users --- **Ready to contribute?** Start by exploring the codebase, reading the architecture documentation, and finding an area that interests you. Every contribution makes Archon better for the entire AI development community. ================================================ FILE: LICENSE ================================================ Archon Community License (ACL) v1.2 Copyright © 2025 The Archon Project Community Maintained by the [Dynamous community](https://dynamous.ai) Archon is **free, open, and hackable.** Run it, fork it, and share it — no strings attached — except one: **don’t sell it as‑a‑service without talking to us first.** --- ### 1  You Can * **Run** Archon anywhere, for anything, for free. * **Study & tweak** the code, add features, change the UI—go wild. * **Share** your changes or forks publicly (must keep this license in place). ### 2  Please Do * Keep this license notice and a link back to the main repo. * Mark clearly if you’ve modified Archon. ### 3  You Can’t (Without Permission) * Charge money for Archon itself—e.g. paid downloads, paywalled builds, or subscriptions. * Offer Archon (original or modified) as a hosted or managed service that others can sign up for. * Bundle Archon into another paid product. > **Consulting/support is totally fine.** Get paid to install, customise, or teach Archon as long as your clients don’t get a hosted Archon instance run by you. ### 4  No Warranty Archon comes **as‑is** with **no warranty** of any kind. ### 5  Limitation of Liability We’re **not liable** for any damages resulting from using Archon. ### 6  Breaking the Rules If you violate these terms and don’t fix it within **30 days** after we let you know, your rights under this license end. ================================================ FILE: Makefile ================================================ # Archon Makefile - Simple, Secure, Cross-Platform SHELL := /bin/bash .SHELLFLAGS := -ec # Docker compose command - prefer newer 'docker compose' plugin over standalone 'docker-compose' COMPOSE ?= $(shell docker compose version >/dev/null 2>&1 && echo "docker compose" || echo "docker-compose") .PHONY: help dev dev-docker dev-docker-full dev-work-orders dev-hybrid-work-orders stop test test-fe test-be lint lint-fe lint-be clean install check agent-work-orders help: @echo "Archon Development Commands" @echo "===========================" @echo " make dev - Backend in Docker, frontend local (recommended)" @echo " make dev-docker - Backend + frontend in Docker" @echo " make dev-docker-full - Everything in Docker (server + mcp + ui + work orders)" @echo " make dev-hybrid-work-orders - Server + MCP in Docker, UI + work orders local (2 terminals)" @echo " make dev-work-orders - Backend in Docker, agent work orders local, frontend local" @echo " make agent-work-orders - Run agent work orders service locally" @echo " make stop - Stop all services" @echo " make test - Run all tests" @echo " make test-fe - Run frontend tests only" @echo " make test-be - Run backend tests only" @echo " make lint - Run all linters" @echo " make lint-fe - Run frontend linter only" @echo " make lint-be - Run backend linter only" @echo " make clean - Remove containers and volumes" @echo " make install - Install dependencies" @echo " make check - Check environment setup" # Install dependencies install: @echo "Installing dependencies..." @cd archon-ui-main && npm install @cd python && uv sync --group all --group dev @echo "✓ Dependencies installed" # Check environment check: @echo "Checking environment..." @node -v >/dev/null 2>&1 || { echo "✗ Node.js not found (require Node 18+)."; exit 1; } @node check-env.js @echo "Checking Docker..." @docker --version > /dev/null 2>&1 || { echo "✗ Docker not found"; exit 1; } @$(COMPOSE) version > /dev/null 2>&1 || { echo "✗ Docker Compose not found"; exit 1; } @echo "✓ Environment OK" # Hybrid development (recommended) dev: check @echo "Starting hybrid development..." @echo "Backend: Docker | Frontend: Local with hot reload" @$(COMPOSE) --profile backend up -d --build @set -a; [ -f .env ] && . ./.env; set +a; \ echo "Backend running at http://$${HOST:-localhost}:$${ARCHON_SERVER_PORT:-8181}" @echo "Starting frontend..." @cd archon-ui-main && \ VITE_ARCHON_SERVER_PORT=$${ARCHON_SERVER_PORT:-8181} \ VITE_ARCHON_SERVER_HOST=$${HOST:-} \ npm run dev # Full Docker development (backend + frontend, no work orders) dev-docker: check @echo "Starting Docker environment (backend + frontend)..." @$(COMPOSE) --profile full up -d --build @echo "✓ Services running" @echo "Frontend: http://localhost:3737" @echo "API: http://localhost:8181" # Full Docker with all services (server + mcp + ui + agent work orders) dev-docker-full: check @echo "Starting full Docker environment with agent work orders..." @$(COMPOSE) up archon-server archon-mcp archon-frontend archon-agent-work-orders -d --build @set -a; [ -f .env ] && . ./.env; set +a; \ echo "✓ All services running"; \ echo "Frontend: http://localhost:3737"; \ echo "API: http://$${HOST:-localhost}:$${ARCHON_SERVER_PORT:-8181}"; \ echo "MCP: http://$${HOST:-localhost}:$${ARCHON_MCP_PORT:-8051}"; \ echo "Agent Work Orders: http://$${HOST:-localhost}:$${AGENT_WORK_ORDERS_PORT:-8053}" # Agent work orders service locally (standalone) agent-work-orders: @echo "Starting Agent Work Orders service locally..." @set -a; [ -f .env ] && . ./.env; set +a; \ export SERVICE_DISCOVERY_MODE=local; \ export ARCHON_SERVER_URL=http://localhost:$${ARCHON_SERVER_PORT:-8181}; \ export ARCHON_MCP_URL=http://localhost:$${ARCHON_MCP_PORT:-8051}; \ export AGENT_WORK_ORDERS_PORT=$${AGENT_WORK_ORDERS_PORT:-8053}; \ cd python && uv run python -m uvicorn src.agent_work_orders.server:app --host 0.0.0.0 --port $${AGENT_WORK_ORDERS_PORT:-8053} --reload # Hybrid development with agent work orders (backend in Docker, agent work orders local, frontend local) dev-work-orders: check @echo "Starting hybrid development with agent work orders..." @echo "Backend: Docker | Agent Work Orders: Local | Frontend: Local" @$(COMPOSE) up archon-server archon-mcp -d --build @set -a; [ -f .env ] && . ./.env; set +a; \ echo "Backend running at http://$${HOST:-localhost}:$${ARCHON_SERVER_PORT:-8181}"; \ echo "Starting agent work orders service..."; \ echo "Run in separate terminal: make agent-work-orders"; \ echo "Starting frontend..."; \ cd archon-ui-main && \ VITE_ARCHON_SERVER_PORT=$${ARCHON_SERVER_PORT:-8181} \ VITE_ARCHON_SERVER_HOST=$${HOST:-} \ npm run dev # Hybrid development: Server + MCP in Docker, UI + Work Orders local (requires 2 terminals) dev-hybrid-work-orders: check @echo "Starting hybrid development: Server + MCP in Docker, UI + Work Orders local" @echo "================================================================" @$(COMPOSE) up archon-server archon-mcp -d --build @set -a; [ -f .env ] && . ./.env; set +a; \ echo ""; \ echo "✓ Server + MCP running in Docker"; \ echo " Server: http://$${HOST:-localhost}:$${ARCHON_SERVER_PORT:-8181}"; \ echo " MCP: http://$${HOST:-localhost}:$${ARCHON_MCP_PORT:-8051}"; \ echo ""; \ echo "Next steps:"; \ echo " 1. Terminal 1 (this one): Press Ctrl+C when done"; \ echo " 2. Terminal 2: make agent-work-orders"; \ echo " 3. Terminal 3: cd archon-ui-main && npm run dev"; \ echo ""; \ echo "Or use 'make dev-docker-full' to run everything in Docker."; \ @read -p "Press Enter to continue or Ctrl+C to stop..." _ # Stop all services stop: @echo "Stopping all services..." @$(COMPOSE) --profile backend --profile frontend --profile full --profile work-orders down @echo "✓ Services stopped" # Run all tests test: test-fe test-be # Run frontend tests test-fe: @echo "Running frontend tests..." @cd archon-ui-main && npm test # Run backend tests test-be: @echo "Running backend tests..." @cd python && uv run pytest # Run all linters lint: lint-fe lint-be # Run frontend linter lint-fe: @echo "Linting frontend..." @cd archon-ui-main && npm run lint # Run backend linter lint-be: @echo "Linting backend..." @cd python && uv run ruff check --fix # Clean everything (with confirmation) clean: @echo "⚠️ This will remove all containers and volumes" @read -p "Are you sure? (y/N) " -n 1 -r; \ echo; \ if [[ $$REPLY =~ ^[Yy]$$ ]]; then \ $(COMPOSE) down -v --remove-orphans; \ echo "✓ Cleaned"; \ else \ echo "Cancelled"; \ fi .DEFAULT_GOAL := help ================================================ FILE: PRPs/ai_docs/AGENT_WORK_ORDERS_SSE_AND_ZUSTAND.md ================================================ # Agent Work Orders: SSE + Zustand State Management Standards ## Purpose This document defines the **complete architecture, patterns, and standards** for implementing Zustand state management with Server-Sent Events (SSE) in the Agent Work Orders feature. It serves as the authoritative reference for: - State management boundaries (what goes in Zustand vs TanStack Query vs local useState) - SSE integration patterns and connection management - Zustand slice organization and naming conventions - Anti-patterns to avoid - Migration strategy and implementation plan **This is a pilot feature** - patterns established here will be applied to other features (Knowledge Base, Projects, Settings). --- ## Current State Analysis ### Component Structure - **Total Lines:** ~4,400 lines - **Components:** 10 (RepositoryCard, WorkOrderTable, modals, etc.) - **Views:** 2 (AgentWorkOrdersView, AgentWorkOrderDetailView) - **Hooks:** 4 (useAgentWorkOrderQueries, useRepositoryQueries, useWorkOrderLogs, useLogStats) - **Services:** 2 (agentWorkOrdersService, repositoryService) ### Current State Management (42 useState calls) **AgentWorkOrdersView (8 state variables):** ```typescript const [layoutMode, setLayoutMode] = useState(getInitialLayoutMode); const [sidebarExpanded, setSidebarExpanded] = useState(true); const [showAddRepoModal, setShowAddRepoModal] = useState(false); const [showEditRepoModal, setShowEditRepoModal] = useState(false); const [editingRepository, setEditingRepository] = useState(null); const [showNewWorkOrderModal, setShowNewWorkOrderModal] = useState(false); const [searchQuery, setSearchQuery] = useState(""); const selectedRepositoryId = searchParams.get("repo") || undefined; ``` **Problems:** - Manual localStorage management (layoutMode) - Prop drilling for modal controls - No persistence for searchQuery or sidebarExpanded - Scattered state across multiple useState calls --- ## SSE Architecture (Already Implemented!) ### Backend SSE Streams **1. Log Stream (✅ Complete)** ``` GET /api/agent-work-orders/{id}/logs/stream ``` **What it provides:** - Real-time structured logs from workflow execution - Event types: `workflow_started`, `step_started`, `step_completed`, `workflow_completed`, `workflow_failed` - Rich metadata in each log: `step`, `step_number`, `total_steps`, `progress`, `progress_pct`, `elapsed_seconds` - Filters: level, step, since timestamp - Heartbeat every 15 seconds **Frontend Integration:** - ✅ `useWorkOrderLogs` hook - EventSource connection with auto-reconnect - ✅ `useLogStats` hook - Parses logs to extract progress metrics - ✅ `RealTimeStats` component - Now uses real SSE data (was mock) - ✅ `ExecutionLogs` component - Now displays real logs (was mock) **Key Insight:** SSE logs contain ALL progress information including: - Current step and progress percentage - Elapsed time - Step completion status - Git stats (from log events) - Workflow lifecycle events --- ### Current Polling (Should Be Replaced) **useWorkOrders() - Polls every 3s:** ```typescript refetchInterval: (query) => { const hasActiveWorkOrders = data?.some((wo) => wo.status === "running" || wo.status === "pending"); return hasActiveWorkOrders ? 3000 : false; } ``` **useWorkOrder(id) - Polls every 3s:** ```typescript refetchInterval: (query) => { if (data?.status === "running" || data?.status === "pending") { return 3000; } return false; } ``` **useStepHistory(id) - Polls every 3s:** ```typescript refetchInterval: (query) => { const lastStep = history?.steps[history.steps.length - 1]; if (lastStep?.step === "create-pr" && lastStep?.success) { return false; } return 3000; } ``` **Network Impact:** - 3 active work orders = ~140 HTTP requests/minute - With ETags: ~50-100KB/minute bandwidth - Up to 3 second delay for updates --- ## Zustand State Management Standards ### Core Principles **1. State Categorization:** - **UI Preferences** → Zustand (persisted) - **Modal State** → Zustand (NOT persisted) - **Filter State** → Zustand (persisted) - **SSE Connections** → Zustand (NOT persisted) - **Server Data** → TanStack Query (cached) - **Form State** → Zustand slices OR local useState (depends on complexity) - **Ephemeral UI** → Local useState (component-specific) **2. Selective Subscriptions:** ```typescript // ✅ GOOD - Only re-renders when layoutMode changes const layoutMode = useAgentWorkOrdersStore((s) => s.layoutMode); const setLayoutMode = useAgentWorkOrdersStore((s) => s.setLayoutMode); // ❌ BAD - Re-renders on ANY state change const { layoutMode, searchQuery, selectedRepositoryId } = useAgentWorkOrdersStore(); ``` **3. Server State Boundary:** ```typescript // ✅ GOOD - TanStack Query for initial load, mutations, caching const { data: repositories } = useRepositories(); // ✅ GOOD - Zustand for real-time SSE updates const liveWorkOrder = useAgentWorkOrdersStore((s) => s.liveWorkOrders[id]); // ✅ GOOD - Combine them const workOrder = liveWorkOrder || cachedWorkOrder; // SSE overrides cache // ❌ BAD - Duplicating server state in Zustand const repositories = useAgentWorkOrdersStore((s) => s.repositories); // DON'T DO THIS ``` **4. Slice Organization:** - One slice per concern (modals, UI prefs, filters, SSE) - Each slice is independently testable - Slices can reference each other via get() - Use TypeScript for all slice types --- ## Zustand Store Structure ### File Organization ``` src/features/agent-work-orders/state/ ├── agentWorkOrdersStore.ts # Main store combining slices ├── slices/ │ ├── uiPreferencesSlice.ts # Layout, sidebar state │ ├── modalsSlice.ts # Modal visibility & context │ ├── filtersSlice.ts # Search, selected repo │ └── sseSlice.ts # SSE connections & live data └── __tests__/ └── agentWorkOrdersStore.test.ts # Store tests ``` --- ### Main Store (agentWorkOrdersStore.ts) ```typescript import { create } from 'zustand'; import { persist, devtools, subscribeWithSelector } from 'zustand/middleware'; import { createUIPreferencesSlice, type UIPreferencesSlice } from './slices/uiPreferencesSlice'; import { createModalsSlice, type ModalsSlice } from './slices/modalsSlice'; import { createFiltersSlice, type FiltersSlice } from './slices/filtersSlice'; import { createSSESlice, type SSESlice } from './slices/sseSlice'; /** * Combined Agent Work Orders store type * Combines all slices into a single store interface */ export type AgentWorkOrdersStore = & UIPreferencesSlice & ModalsSlice & FiltersSlice & SSESlice; /** * Agent Work Orders global state store * * Manages: * - UI preferences (layout mode, sidebar state) - PERSISTED * - Modal state (which modal is open, editing context) - NOT persisted * - Filter state (search query, selected repository) - PERSISTED * - SSE connections (live updates, connection management) - NOT persisted * * Does NOT manage: * - Server data (TanStack Query handles this) * - Ephemeral UI state (local useState for row expansion, etc.) */ export const useAgentWorkOrdersStore = create()( devtools( subscribeWithSelector( persist( (...a) => ({ ...createUIPreferencesSlice(...a), ...createModalsSlice(...a), ...createFiltersSlice(...a), ...createSSESlice(...a), }), { name: 'agent-work-orders-ui', version: 1, partialize: (state) => ({ // Only persist UI preferences and filters layoutMode: state.layoutMode, sidebarExpanded: state.sidebarExpanded, searchQuery: state.searchQuery, // Do NOT persist: // - Modal state (ephemeral) // - SSE connections (must be re-established) // - Live data (should be fresh on reload) }), } ) ), { name: 'AgentWorkOrders' } ) ); ``` --- ### UI Preferences Slice ```typescript // src/features/agent-work-orders/state/slices/uiPreferencesSlice.ts import { StateCreator } from 'zustand'; export type LayoutMode = 'horizontal' | 'sidebar'; export type UIPreferencesSlice = { // State layoutMode: LayoutMode; sidebarExpanded: boolean; // Actions setLayoutMode: (mode: LayoutMode) => void; setSidebarExpanded: (expanded: boolean) => void; toggleSidebar: () => void; resetUIPreferences: () => void; }; /** * UI Preferences Slice * * Manages user interface preferences that should persist across sessions. * Includes layout mode (horizontal/sidebar) and sidebar expansion state. * * Persisted: YES (via persist middleware in main store) */ export const createUIPreferencesSlice: StateCreator< UIPreferencesSlice, [], [], UIPreferencesSlice > = (set) => ({ // Initial state layoutMode: 'sidebar', sidebarExpanded: true, // Actions setLayoutMode: (mode) => set({ layoutMode: mode }), setSidebarExpanded: (expanded) => set({ sidebarExpanded: expanded }), toggleSidebar: () => set((state) => ({ sidebarExpanded: !state.sidebarExpanded })), resetUIPreferences: () => set({ layoutMode: 'sidebar', sidebarExpanded: true, }), }); ``` **Replaces:** - Manual localStorage get/set (~20 lines eliminated) - getInitialLayoutMode, saveLayoutMode functions - useState for layoutMode and sidebarExpanded --- ### Modals Slice (With Optional Form State) ```typescript // src/features/agent-work-orders/state/slices/modalsSlice.ts import { StateCreator } from 'zustand'; import type { ConfiguredRepository } from '../../types/repository'; import type { WorkflowStep } from '../../types'; export type ModalsSlice = { // Modal visibility showAddRepoModal: boolean; showEditRepoModal: boolean; showCreateWorkOrderModal: boolean; // Modal context (which item is being edited) editingRepository: ConfiguredRepository | null; preselectedRepositoryId: string | undefined; // Actions openAddRepoModal: () => void; closeAddRepoModal: () => void; openEditRepoModal: (repository: ConfiguredRepository) => void; closeEditRepoModal: () => void; openCreateWorkOrderModal: (repositoryId?: string) => void; closeCreateWorkOrderModal: () => void; closeAllModals: () => void; }; /** * Modals Slice * * Manages modal visibility and context (which repository is being edited, etc.). * Enables opening modals from anywhere without prop drilling. * * Persisted: NO (modals should not persist across page reloads) * * Note: Form state (repositoryUrl, selectedSteps, etc.) can be added to this slice * if centralized validation/submission logic is desired. For simple forms that * reset on close, local useState in the modal component is cleaner. */ export const createModalsSlice: StateCreator< ModalsSlice, [], [], ModalsSlice > = (set) => ({ // Initial state showAddRepoModal: false, showEditRepoModal: false, showCreateWorkOrderModal: false, editingRepository: null, preselectedRepositoryId: undefined, // Actions openAddRepoModal: () => set({ showAddRepoModal: true }), closeAddRepoModal: () => set({ showAddRepoModal: false }), openEditRepoModal: (repository) => set({ showEditRepoModal: true, editingRepository: repository, }), closeEditRepoModal: () => set({ showEditRepoModal: false, editingRepository: null, }), openCreateWorkOrderModal: (repositoryId) => set({ showCreateWorkOrderModal: true, preselectedRepositoryId: repositoryId, }), closeCreateWorkOrderModal: () => set({ showCreateWorkOrderModal: false, preselectedRepositoryId: undefined, }), closeAllModals: () => set({ showAddRepoModal: false, showEditRepoModal: false, showCreateWorkOrderModal: false, editingRepository: null, preselectedRepositoryId: undefined, }), }); ``` **Replaces:** - Multiple useState calls for modal visibility (~5 states) - handleEditRepository, handleCreateWorkOrder helper functions - Prop drilling for modal open/close callbacks --- ### Filters Slice ```typescript // src/features/agent-work-orders/state/slices/filtersSlice.ts import { StateCreator } from 'zustand'; export type FiltersSlice = { // State searchQuery: string; selectedRepositoryId: string | undefined; // Actions setSearchQuery: (query: string) => void; selectRepository: (id: string | undefined, syncUrl?: (id: string | undefined) => void) => void; clearFilters: () => void; }; /** * Filters Slice * * Manages filter and selection state for repositories and work orders. * Includes search query and selected repository ID. * * Persisted: YES (search/selection survives reload) * * URL Sync: selectedRepositoryId should also update URL query params. * Use the syncUrl callback to keep URL in sync. */ export const createFiltersSlice: StateCreator< FiltersSlice, [], [], FiltersSlice > = (set) => ({ // Initial state searchQuery: '', selectedRepositoryId: undefined, // Actions setSearchQuery: (query) => set({ searchQuery: query }), selectRepository: (id, syncUrl) => { set({ selectedRepositoryId: id }); // Callback to sync with URL search params syncUrl?.(id); }, clearFilters: () => set({ searchQuery: '', selectedRepositoryId: undefined, }), }); ``` **Replaces:** - useState for searchQuery - Manual selectRepository function - Enables global filtering in future --- ### SSE Slice (Replaces Polling!) ```typescript // src/features/agent-work-orders/state/slices/sseSlice.ts import { StateCreator } from 'zustand'; import type { AgentWorkOrder, StepExecutionResult, LogEntry } from '../../types'; export type SSESlice = { // Active EventSource connections (keyed by work_order_id) logConnections: Map; // Connection states connectionStates: Record; // Live data from SSE (keyed by work_order_id) // This OVERLAYS on top of TanStack Query cached data liveLogs: Record; liveProgress: Record; // Actions connectToLogs: (workOrderId: string) => void; disconnectFromLogs: (workOrderId: string) => void; handleLogEvent: (workOrderId: string, log: LogEntry) => void; clearLogs: (workOrderId: string) => void; disconnectAll: () => void; }; /** * SSE Slice * * Manages Server-Sent Event connections and real-time data from log streams. * Handles connection lifecycle, auto-reconnect, and live data aggregation. * * Persisted: NO (connections must be re-established on page load) * * Pattern: * 1. Component calls connectToLogs(workOrderId) on mount * 2. Zustand creates EventSource if not exists * 3. Multiple components can subscribe to same connection * 4. handleLogEvent parses logs and updates liveProgress * 5. Component calls disconnectFromLogs on unmount * 6. Zustand closes EventSource when no more subscribers */ export const createSSESlice: StateCreator = (set, get) => ({ // Initial state logConnections: new Map(), connectionStates: {}, liveLogs: {}, liveProgress: {}, // Actions connectToLogs: (workOrderId) => { const { logConnections, connectionStates } = get(); // Don't create duplicate connections if (logConnections.has(workOrderId)) { return; } // Set connecting state set((state) => ({ connectionStates: { ...state.connectionStates, [workOrderId]: 'connecting', }, })); // Create EventSource for log stream const url = `/api/agent-work-orders/${workOrderId}/logs/stream`; const eventSource = new EventSource(url); eventSource.onopen = () => { set((state) => ({ connectionStates: { ...state.connectionStates, [workOrderId]: 'connected', }, })); }; eventSource.onmessage = (event) => { try { const logEntry: LogEntry = JSON.parse(event.data); get().handleLogEvent(workOrderId, logEntry); } catch (err) { console.error('Failed to parse log entry:', err); } }; eventSource.onerror = () => { set((state) => ({ connectionStates: { ...state.connectionStates, [workOrderId]: 'error', }, })); // Auto-reconnect after 5 seconds setTimeout(() => { eventSource.close(); logConnections.delete(workOrderId); get().connectToLogs(workOrderId); // Retry }, 5000); }; // Store connection logConnections.set(workOrderId, eventSource); set({ logConnections: new Map(logConnections) }); }, disconnectFromLogs: (workOrderId) => { const { logConnections } = get(); const connection = logConnections.get(workOrderId); if (connection) { connection.close(); logConnections.delete(workOrderId); set({ logConnections: new Map(logConnections), connectionStates: { ...get().connectionStates, [workOrderId]: 'disconnected', }, }); } }, handleLogEvent: (workOrderId, log) => { // Add to logs array set((state) => ({ liveLogs: { ...state.liveLogs, [workOrderId]: [...(state.liveLogs[workOrderId] || []), log].slice(-500), // Keep last 500 }, })); // Parse log to update progress const progressUpdate: any = {}; if (log.event === 'step_started') { progressUpdate.currentStep = log.step; progressUpdate.stepNumber = log.step_number; progressUpdate.totalSteps = log.total_steps; } if (log.progress_pct !== undefined) { progressUpdate.progressPct = log.progress_pct; } if (log.elapsed_seconds !== undefined) { progressUpdate.elapsedSeconds = log.elapsed_seconds; } if (log.event === 'workflow_completed') { progressUpdate.status = 'completed'; } if (log.event === 'workflow_failed' || log.level === 'error') { progressUpdate.status = 'failed'; } if (Object.keys(progressUpdate).length > 0) { set((state) => ({ liveProgress: { ...state.liveProgress, [workOrderId]: { ...state.liveProgress[workOrderId], ...progressUpdate, }, }, })); } }, clearLogs: (workOrderId) => { set((state) => ({ liveLogs: { ...state.liveLogs, [workOrderId]: [], }, })); }, disconnectAll: () => { const { logConnections } = get(); logConnections.forEach((conn) => conn.close()); set({ logConnections: new Map(), connectionStates: {}, liveLogs: {}, liveProgress: {}, }); }, }); ``` --- ## Component Integration Patterns ### Pattern 1: RealTimeStats (SSE + Zustand) **Current (just fixed):** ```typescript export function RealTimeStats({ workOrderId }: RealTimeStatsProps) { const { logs } = useWorkOrderLogs({ workOrderId }); // Direct SSE hook const stats = useLogStats(logs); // Parse logs // Display stats.currentStep, stats.progressPct, etc. } ``` **With Zustand SSE Slice:** ```typescript export function RealTimeStats({ workOrderId }: RealTimeStatsProps) { // Connect to SSE (Zustand manages connection) const connectToLogs = useAgentWorkOrdersStore((s) => s.connectToLogs); const disconnectFromLogs = useAgentWorkOrdersStore((s) => s.disconnectFromLogs); useEffect(() => { connectToLogs(workOrderId); return () => disconnectFromLogs(workOrderId); }, [workOrderId]); // Subscribe to parsed progress (Zustand parses logs automatically) const progress = useAgentWorkOrdersStore((s) => s.liveProgress[workOrderId]); // Display progress.currentStep, progress.progressPct, etc. // No need for useLogStats - Zustand already parsed it! } ``` **Benefits:** - Zustand handles connection lifecycle - Multiple components can display progress without multiple connections - Automatic cleanup when all subscribers unmount --- ### Pattern 2: WorkOrderRow (Hybrid TanStack + Zustand) **Current:** ```typescript const { data: workOrder } = useWorkOrder(id); // Polls every 3s ``` **With Zustand:** ```typescript // Initial load from TanStack Query (cached, no polling) const { data: cachedWorkOrder } = useWorkOrder(id, { refetchInterval: false, // NO MORE POLLING! }); // Live updates from SSE (via Zustand) const liveProgress = useAgentWorkOrdersStore((s) => s.liveProgress[id]); // Merge: SSE overrides cached data const workOrder = { ...cachedWorkOrder, ...liveProgress, // status, git_commit_count, etc. from SSE }; ``` **Benefits:** - No polling (0 HTTP requests while connected) - Instant updates from SSE - TanStack Query still handles initial load, mutations, caching --- ### Pattern 3: Modal Management (No Prop Drilling) **Current:** ```typescript // AgentWorkOrdersView const [showEditRepoModal, setShowEditRepoModal] = useState(false); const [editingRepository, setEditingRepository] = useState(null); const handleEditRepository = (repository: ConfiguredRepository) => { setEditingRepository(repository); setShowEditRepoModal(true); }; // Pass down to child handleEditRepository(repository)} /> ``` **With Zustand:** ```typescript // RepositoryCard (no props needed) const openEditRepoModal = useAgentWorkOrdersStore((s) => s.openEditRepoModal); // AgentWorkOrdersView (just renders modal) const showEditRepoModal = useAgentWorkOrdersStore((s) => s.showEditRepoModal); const closeEditRepoModal = useAgentWorkOrdersStore((s) => s.closeEditRepoModal); const editingRepository = useAgentWorkOrdersStore((s) => s.editingRepository); ``` **Benefits:** - Can open modal from anywhere (breadcrumb, keyboard shortcut, etc.) - No callback props - Cleaner component tree --- ## Anti-Patterns (DO NOT DO) ### ❌ Anti-Pattern 1: Subscribing to Full Store ```typescript // BAD - Component re-renders on ANY state change const store = useAgentWorkOrdersStore(); const { layoutMode, searchQuery, selectedRepositoryId } = store; ``` **Why bad:** - Component re-renders even if only unrelated state changes - Defeats the purpose of Zustand's selective subscriptions **Fix:** ```typescript // GOOD - Only re-renders when layoutMode changes const layoutMode = useAgentWorkOrdersStore((s) => s.layoutMode); ``` --- ### ❌ Anti-Pattern 2: Duplicating Server State ```typescript // BAD - Storing server data in Zustand type BadSlice = { repositories: ConfiguredRepository[]; workOrders: AgentWorkOrder[]; isLoadingRepos: boolean; fetchRepositories: () => Promise; }; ``` **Why bad:** - Reimplements TanStack Query (caching, invalidation, optimistic updates) - Loses Query features (background refetch, deduplication, etc.) - Increases complexity **Fix:** ```typescript // GOOD - TanStack Query for server data const { data: repositories } = useRepositories(); // GOOD - Zustand ONLY for SSE overlays const liveUpdates = useAgentWorkOrdersStore((s) => s.liveWorkOrders); ``` --- ### ❌ Anti-Pattern 3: Putting Everything in Global State ```typescript // BAD - Form state in Zustand when it shouldn't be type BadSlice = { addRepoForm: { repositoryUrl: string; error: string; isSubmitting: boolean; }; expandedWorkOrderRows: Set; // Per-row state in global store! }; ``` **Why bad:** - Clutters global state with component-local concerns - Forms that reset on close don't need global state - Row expansion is per-instance, not global **Fix:** ```typescript // GOOD - Local useState for simple forms export function AddRepositoryModal() { const [repositoryUrl, setRepositoryUrl] = useState(""); const [error, setError] = useState(""); // Resets on modal close - perfect for local state } // GOOD - Local useState for per-component UI export function WorkOrderRow() { const [isExpanded, setIsExpanded] = useState(false); // Each row has its own expansion state } ``` --- ### ❌ Anti-Pattern 4: Using getState() in Render Logic ```typescript // BAD - Doesn't subscribe to changes function MyComponent() { const layoutMode = useAgentWorkOrdersStore.getState().layoutMode; // Component won't re-render when layoutMode changes! } ``` **Why bad:** - getState() doesn't create a subscription - Component won't re-render on state changes - Silent bugs **Fix:** ```typescript // GOOD - Proper subscription const layoutMode = useAgentWorkOrdersStore((s) => s.layoutMode); ``` --- ### ❌ Anti-Pattern 5: Not Cleaning Up SSE Connections ```typescript // BAD - Connection leaks useEffect(() => { connectToLogs(workOrderId); // Missing cleanup! }, [workOrderId]); ``` **Why bad:** - EventSource connections stay open forever - Memory leaks - Browser connection limit (6 per domain) **Fix:** ```typescript // GOOD - Cleanup on unmount useEffect(() => { connectToLogs(workOrderId); return () => disconnectFromLogs(workOrderId); }, [workOrderId]); ``` --- ## Implementation Checklist ### Phase 1: Zustand Foundation (Frontend Only) - [ ] Create `agentWorkOrdersStore.ts` with slice pattern - [ ] Create `uiPreferencesSlice.ts` (layoutMode, sidebarExpanded) - [ ] Create `modalsSlice.ts` (modal visibility, editing context) - [ ] Create `filtersSlice.ts` (searchQuery, selectedRepositoryId) - [ ] Add persist middleware (only UI prefs and filters) - [ ] Add devtools middleware - [ ] Write store tests **Expected Changes:** - +350 lines (store + slices) - -50 lines (remove localStorage boilerplate, helper functions) - Net: +300 lines --- ### Phase 2: Migrate AgentWorkOrdersView (Frontend Only) - [ ] Replace useState with Zustand selectors - [ ] Remove localStorage helper functions (getInitialLayoutMode, saveLayoutMode) - [ ] Remove modal helper functions (handleEditRepository, etc.) - [ ] Update modal open/close to use Zustand actions - [ ] Sync selectedRepositoryId with URL params - [ ] Test thoroughly (layouts, modals, navigation) **Expected Changes:** - AgentWorkOrdersView: -40 lines (400 → 360) - Eliminate prop drilling for modal callbacks --- ### Phase 3: SSE Integration (Frontend Only) - [ ] Already done! RealTimeStats now uses real SSE data - [ ] Already done! ExecutionLogs now displays real logs - [ ] Verify SSE connection works in browser - [ ] Check Network tab for `/logs/stream` connection - [ ] Verify logs appear in real-time **Expected Changes:** - None needed - just fixed mock data usage --- ### Phase 4: Remove Polling (Frontend Only) - [ ] Create `sseSlice.ts` for connection management - [ ] Add `connectToLogs`, `disconnectFromLogs` actions - [ ] Add `handleLogEvent` to parse logs and update liveProgress - [ ] Update RealTimeStats to use Zustand SSE slice - [ ] Remove `refetchInterval` from `useWorkOrder(id)` - [ ] Remove `refetchInterval` from `useStepHistory(id)` - [ ] Remove `refetchInterval` from `useWorkOrders()` (optional - list updates are less critical) - [ ] Test that status/progress updates appear instantly **Expected Changes:** - +150 lines (SSE slice) - -40 lines (remove polling logic) - Net: +110 lines --- ### Phase 5: Testing & Documentation - [ ] Unit tests for all slices - [ ] Integration test: Create work order → Watch SSE updates → Verify UI updates - [ ] Test SSE reconnection on connection loss - [ ] Test multiple components subscribing to same work order - [ ] Document patterns in this file - [ ] Update ZUSTAND_STATE_MANAGEMENT.md with agent work orders examples --- ## Testing Standards ### Store Testing ```typescript // agentWorkOrdersStore.test.ts import { useAgentWorkOrdersStore } from './agentWorkOrdersStore'; describe('AgentWorkOrdersStore', () => { beforeEach(() => { // Reset store to initial state useAgentWorkOrdersStore.setState({ layoutMode: 'sidebar', sidebarExpanded: true, searchQuery: '', selectedRepositoryId: undefined, showAddRepoModal: false, // ... reset all state }); }); it('should toggle layout mode and persist', () => { const { setLayoutMode } = useAgentWorkOrdersStore.getState(); setLayoutMode('horizontal'); expect(useAgentWorkOrdersStore.getState().layoutMode).toBe('horizontal'); // Check localStorage persistence const persisted = JSON.parse(localStorage.getItem('agent-work-orders-ui') || '{}'); expect(persisted.state.layoutMode).toBe('horizontal'); }); it('should manage modal state without persistence', () => { const { openEditRepoModal, closeEditRepoModal } = useAgentWorkOrdersStore.getState(); const mockRepo = { id: '1', repository_url: 'https://github.com/test/repo' } as ConfiguredRepository; openEditRepoModal(mockRepo); expect(useAgentWorkOrdersStore.getState().showEditRepoModal).toBe(true); expect(useAgentWorkOrdersStore.getState().editingRepository).toBe(mockRepo); closeEditRepoModal(); expect(useAgentWorkOrdersStore.getState().showEditRepoModal).toBe(false); expect(useAgentWorkOrdersStore.getState().editingRepository).toBe(null); // Verify modals NOT persisted const persisted = JSON.parse(localStorage.getItem('agent-work-orders-ui') || '{}'); expect(persisted.state.showEditRepoModal).toBeUndefined(); }); it('should handle SSE log events and parse progress', () => { const { handleLogEvent } = useAgentWorkOrdersStore.getState(); const workOrderId = 'wo-123'; const stepStartedLog: LogEntry = { work_order_id: workOrderId, level: 'info', event: 'step_started', timestamp: new Date().toISOString(), step: 'planning', step_number: 2, total_steps: 5, progress_pct: 40, }; handleLogEvent(workOrderId, stepStartedLog); const progress = useAgentWorkOrdersStore.getState().liveProgress[workOrderId]; expect(progress.currentStep).toBe('planning'); expect(progress.stepNumber).toBe(2); expect(progress.progressPct).toBe(40); }); }); ``` --- ## Performance Expectations ### Current (With Polling) - **HTTP Requests:** 140/min (3 active work orders) - **Bandwidth:** 50-100KB/min (with ETags) - **Latency:** Up to 3 second delay for updates - **Client CPU:** Moderate (constant polling, re-renders) ### After (With SSE + Zustand) - **HTTP Requests:** ~14/min (only for mutations and initial loads) - **SSE Connections:** 1-5 persistent connections - **Bandwidth:** 5-10KB/min (events only, no 304 overhead) - **Latency:** <100ms (instant SSE delivery) - **Client CPU:** Lower (event-driven, selective re-renders) **Savings: 90% bandwidth reduction, 95% request reduction, instant updates** --- ## Migration Risk Assessment ### Low Risk - ✅ UI Preferences slice (localStorage → Zustand persist) - ✅ Modals slice (no external dependencies) - ✅ SSE logs integration (already built, just use it) ### Medium Risk - ⚠️ URL sync with Zustand (needs careful testing) - ⚠️ SSE connection management (need proper cleanup) - ⚠️ Selective subscriptions (team must learn pattern) ### High Risk (Don't Do) - ❌ Replacing TanStack Query with Zustand (don't do this!) - ❌ Global state for all forms (overkill) - ❌ Putting row expansion in global state (terrible idea) --- ## Decision Matrix: What Goes Where? | State Type | Current | Should Be | Reason | |------------|---------|-----------|--------| | layoutMode | useState + localStorage | Zustand (persisted) | Automatic persistence, global access | | sidebarExpanded | useState | Zustand (persisted) | Should persist across reloads | | showAddRepoModal | useState | Zustand (not persisted) | Enable opening from anywhere | | editingRepository | useState | Zustand (not persisted) | Context for edit modal | | searchQuery | useState | Zustand (persisted) | Persist search across navigation | | selectedRepositoryId | URL params | Zustand + URL sync (persisted) | Dual source: Zustand cache + URL truth | | repositories (server) | TanStack Query | TanStack Query | Perfect for server state | | workOrders (server) | TanStack Query | TanStack Query + SSE overlay | Initial load (Query), updates (SSE) | | repositoryUrl (form) | useState in modal | useState in modal | Simple, resets on close | | selectedSteps (form) | useState in modal | useState in modal | Simple, resets on close | | isExpanded (row) | useState per row | useState per row | Component-specific | | SSE connections | useWorkOrderLogs hook | Zustand SSE slice | Centralized management | | logs (from SSE) | useWorkOrderLogs hook | Zustand SSE slice | Share across components | | progress (parsed logs) | useLogStats hook | Zustand SSE slice | Auto-parse on event | --- ## Code Examples ### Before: AgentWorkOrdersView (Current) ```typescript export function AgentWorkOrdersView() { // 8 separate useState calls const [layoutMode, setLayoutMode] = useState(getInitialLayoutMode); const [sidebarExpanded, setSidebarExpanded] = useState(true); const [showAddRepoModal, setShowAddRepoModal] = useState(false); const [showEditRepoModal, setShowEditRepoModal] = useState(false); const [editingRepository, setEditingRepository] = useState(null); const [showNewWorkOrderModal, setShowNewWorkOrderModal] = useState(false); const [searchQuery, setSearchQuery] = useState(""); const selectedRepositoryId = searchParams.get("repo") || undefined; // Helper functions (20+ lines) const updateLayoutMode = (mode: LayoutMode) => { setLayoutMode(mode); saveLayoutMode(mode); // Manual localStorage }; const handleEditRepository = (repository: ConfiguredRepository) => { setEditingRepository(repository); setShowEditRepoModal(true); }; // Server data (polls every 3s) const { data: repositories = [] } = useRepositories(); const { data: workOrders = [] } = useWorkOrders(); // Polling! // ... 400 lines total } ``` --- ### After: AgentWorkOrdersView (With Zustand) ```typescript export function AgentWorkOrdersView() { const [searchParams, setSearchParams] = useSearchParams(); // Zustand UI Preferences const layoutMode = useAgentWorkOrdersStore((s) => s.layoutMode); const sidebarExpanded = useAgentWorkOrdersStore((s) => s.sidebarExpanded); const setLayoutMode = useAgentWorkOrdersStore((s) => s.setLayoutMode); const toggleSidebar = useAgentWorkOrdersStore((s) => s.toggleSidebar); // Zustand Modals const showAddRepoModal = useAgentWorkOrdersStore((s) => s.showAddRepoModal); const showEditRepoModal = useAgentWorkOrdersStore((s) => s.showEditRepoModal); const showCreateWorkOrderModal = useAgentWorkOrdersStore((s) => s.showCreateWorkOrderModal); const editingRepository = useAgentWorkOrdersStore((s) => s.editingRepository); const openAddRepoModal = useAgentWorkOrdersStore((s) => s.openAddRepoModal); const openEditRepoModal = useAgentWorkOrdersStore((s) => s.openEditRepoModal); const closeEditRepoModal = useAgentWorkOrdersStore((s) => s.closeEditRepoModal); const openCreateWorkOrderModal = useAgentWorkOrdersStore((s) => s.openCreateWorkOrderModal); const closeCreateWorkOrderModal = useAgentWorkOrdersStore((s) => s.closeCreateWorkOrderModal); // Zustand Filters const searchQuery = useAgentWorkOrdersStore((s) => s.searchQuery); const selectedRepositoryId = useAgentWorkOrdersStore((s) => s.selectedRepositoryId); const setSearchQuery = useAgentWorkOrdersStore((s) => s.setSearchQuery); const selectRepository = useAgentWorkOrdersStore((s) => s.selectRepository); // Sync Zustand with URL params (bidirectional) useEffect(() => { const urlRepoId = searchParams.get("repo") || undefined; if (urlRepoId !== selectedRepositoryId) { selectRepository(urlRepoId, setSearchParams); } }, [searchParams]); // Server data (TanStack Query - NO POLLING after Phase 4) const { data: repositories = [] } = useRepositories(); const { data: cachedWorkOrders = [] } = useWorkOrders({ refetchInterval: false }); // Live updates from SSE (Phase 4) const liveWorkOrders = useAgentWorkOrdersStore((s) => s.liveWorkOrders); const workOrders = cachedWorkOrders.map((wo) => ({ ...wo, ...(liveWorkOrders[wo.agent_work_order_id] || {}), // SSE overrides })); // ... ~360 lines total (-40 lines) } ``` **Changes:** - ✅ No manual localStorage (automatic via persist) - ✅ No helper functions (actions are in store) - ✅ Can open modals from anywhere - ✅ No polling (SSE provides updates) - ❌ More verbose selectors (but clearer intent) --- ## Final Architecture Diagram ``` ┌─────────────────────────────────────────────────────────────┐ │ AgentWorkOrdersView │ │ ┌────────────────┐ ┌──────────────┐ ┌────────────────┐ │ │ │ Zustand Store │ │ TanStack │ │ Components │ │ │ │ │ │ Query │ │ │ │ │ │ ├─ UI Prefs │ │ │ │ ├─ RepoCard │ │ │ │ ├─ Modals │ │ ├─ Repos │ │ ├─ WorkOrder │ │ │ │ ├─ Filters │ │ ├─ WorkOrders│ │ │ Table │ │ │ │ └─ SSE │ │ └─ Mutations │ │ └─ Modals │ │ │ └────────────────┘ └──────────────┘ └────────────────┘ │ │ │ │ │ │ │ └───────────────────┴───────────────────┘ │ │ │ │ └─────────────────────────────┼───────────────────────────────┘ │ ┌─────────────┴─────────────┐ │ │ ┌──────▼──────┐ ┌──────▼──────┐ │ Backend │ │ Backend │ │ REST API │ │ SSE Stream │ │ │ │ │ │ GET /repos │ │ GET /logs/ │ │ POST /wo │ │ stream │ │ PATCH /repo │ │ │ └─────────────┘ └─────────────┘ ``` **Data Flow:** 1. **Initial Load:** TanStack Query → REST API → Cache 2. **Real-Time Updates:** SSE Stream → Zustand SSE Slice → Components 3. **User Actions:** Component → Zustand Action → TanStack Query Mutation → REST API 4. **UI State:** Component → Zustand Selector → Render --- ## Summary ### Use Zustand For: 1. ✅ **UI Preferences** (layoutMode, sidebarExpanded) - Persisted 2. ✅ **Modal State** (visibility, editing context) - NOT persisted 3. ✅ **Filter State** (search, selected repo) - Persisted 4. ✅ **SSE Management** (connections, live data parsing) - NOT persisted ### Use Zustand Slices For: 1. ✅ **Modals** - Clean separation, no prop drilling 2. ✅ **UI Preferences** - Persistence with minimal code 3. ✅ **SSE** - Connection lifecycle management 4. ⚠️ **Forms** - Only if complex validation or "save draft" needed 5. ❌ **Ephemeral UI** - Keep local useState for row expansion, etc. ### Keep TanStack Query For: 1. ✅ **Server Data** - Initial loads, caching, mutations 2. ✅ **Optimistic Updates** - TanStack Query handles this perfectly 3. ✅ **Request Deduplication** - Built-in 4. ✅ **Background Refetch** - For completed work orders (no SSE needed) ### Keep Local useState For: 1. ✅ **Simple Forms** - Reset on close, no sharing needed 2. ✅ **Ephemeral UI** - Row expansion, animation triggers 3. ✅ **Component-Specific** - showLogs toggle in RealTimeStats --- ## Expected Outcomes ### Code Metrics - **Current:** 4,400 lines - **After Phase 4:** 4,890 lines (+490 lines / +11%) - **Net Change:** +350 Zustand, +200 SSE, -60 removed boilerplate ### Performance Metrics - **HTTP Requests:** 140/min → 14/min (-90%) - **Bandwidth:** 50-100KB/min → 5-10KB/min (-90%) - **Update Latency:** 3 seconds → <100ms (-97%) - **Client Re-renders:** Reduced (selective subscriptions) ### Developer Experience - ✅ No manual localStorage management - ✅ No prop drilling for modals - ✅ Truly real-time updates (SSE) - ✅ Better debugging (Zustand DevTools) - ⚠️ Slightly more verbose (selective subscriptions) - ⚠️ Learning curve (Zustand patterns, SSE lifecycle) **Verdict: Net positive - real-time architecture is worth the 11% code increase** --- ## Next Steps **DO NOT IMPLEMENT YET - This document is the reference for creating a PRP.** When creating the PRP: 1. Reference this document for architecture decisions 2. Follow the 5-phase implementation plan 3. Include all anti-patterns as validation gates 4. Add comprehensive test requirements 5. Document Zustand + SSE patterns for other features to follow This is a **pilot feature** - success here validates the pattern for Knowledge Base, Projects, and Settings. ================================================ FILE: PRPs/ai_docs/API_NAMING_CONVENTIONS.md ================================================ # API Naming Conventions ## Overview This document describes the actual naming conventions used throughout Archon's codebase based on current implementation patterns. All examples reference real files where these patterns are implemented. ## Backend API Endpoints ### RESTful Route Patterns **Reference**: `python/src/server/api_routes/projects_api.py` Standard REST patterns used: - `GET /api/{resource}` - List all resources - `POST /api/{resource}` - Create new resource - `GET /api/{resource}/{id}` - Get single resource - `PUT /api/{resource}/{id}` - Update resource - `DELETE /api/{resource}/{id}` - Delete resource Nested resource patterns: - `GET /api/projects/{project_id}/tasks` - Tasks scoped to project - `GET /api/projects/{project_id}/docs` - Documents scoped to project - `POST /api/projects/{project_id}/versions` - Create version for project ### Actual Endpoint Examples From `python/src/server/api_routes/`: **Projects** (`projects_api.py`): - `/api/projects` - Project CRUD - `/api/projects/{project_id}/features` - Get project features - `/api/projects/{project_id}/tasks` - Project-scoped tasks - `/api/projects/{project_id}/docs` - Project documents - `/api/projects/{project_id}/versions` - Version history **Knowledge** (`knowledge_api.py`): - `/api/knowledge/sources` - Knowledge sources - `/api/knowledge/crawl` - Start web crawl - `/api/knowledge/upload` - Upload document - `/api/knowledge/search` - RAG search - `/api/knowledge/code-search` - Code-specific search **Progress** (`progress_api.py`): - `/api/progress/active` - Active operations - `/api/progress/{operation_id}` - Specific operation status **MCP** (`mcp_api.py`): - `/api/mcp/status` - MCP server status - `/api/mcp/execute` - Execute MCP tool ## Frontend Service Methods ### Service Object Pattern **Reference**: `archon-ui-main/src/features/projects/services/projectService.ts` Services are exported as objects with async methods: ```typescript export const serviceNameService = { async methodName(): Promise { ... } } ``` ### Standard Service Method Names Actual patterns from service files: **List Operations**: - `listProjects()` - Get all projects - `getTasksByProject(projectId)` - Get filtered list - `getTasksByStatus(status)` - Get by specific criteria **Single Item Operations**: - `getProject(projectId)` - Get single item - `getTask(taskId)` - Direct ID access **Create Operations**: - `createProject(data)` - Returns created entity - `createTask(data)` - Includes server-generated fields **Update Operations**: - `updateProject(id, updates)` - Partial updates - `updateTaskStatus(id, status)` - Specific field update - `updateTaskOrder(id, order, status?)` - Complex updates **Delete Operations**: - `deleteProject(id)` - Returns void - `deleteTask(id)` - Soft delete pattern ### Service File Locations - **Projects**: `archon-ui-main/src/features/projects/services/projectService.ts` - **Tasks**: `archon-ui-main/src/features/projects/tasks/services/taskService.ts` - **Knowledge**: `archon-ui-main/src/features/knowledge/services/knowledgeService.ts` - **Progress**: `archon-ui-main/src/features/progress/services/progressService.ts` ## React Hook Naming ### Query Hooks **Reference**: `archon-ui-main/src/features/projects/tasks/hooks/useTaskQueries.ts` Standard patterns: - `use[Resource]()` - List query (e.g., `useProjects`) - `use[Resource]Detail(id)` - Single item query - `use[Parent][Resource](parentId)` - Scoped query (e.g., `useProjectTasks`) ### Mutation Hooks - `useCreate[Resource]()` - Creation mutation - `useUpdate[Resource]()` - Update mutation - `useDelete[Resource]()` - Deletion mutation ### Utility Hooks **Reference**: `archon-ui-main/src/features/ui/hooks/` - `useSmartPolling()` - Visibility-aware polling - `useToast()` - Toast notifications - `useDebounce()` - Debounced values ## Type Naming Conventions ### Type Definition Patterns **Reference**: `archon-ui-main/src/features/projects/types/` **Entity Types**: - `Project` - Core entity type - `Task` - Business object - `Document` - Data model **Request/Response Types**: - `Create[Entity]Request` - Creation payload - `Update[Entity]Request` - Update payload - `[Entity]Response` - API response wrapper **Database Types**: - `DatabaseTaskStatus` - Exact database values **Location**: `archon-ui-main/src/features/projects/tasks/types/task.ts` Values: `"todo" | "doing" | "review" | "done"` ### Type File Organization Following vertical slice architecture: - Core types in `{feature}/types/` - Sub-feature types in `{feature}/{subfeature}/types/` - Shared types in `shared/types/` ## Query Key Factories **Reference**: Each feature's `hooks/use{Feature}Queries.ts` file Standard factory pattern: - `{resource}Keys.all` - Base key for invalidation - `{resource}Keys.lists()` - List queries - `{resource}Keys.detail(id)` - Single item queries - `{resource}Keys.byProject(projectId)` - Scoped queries Examples: - `projectKeys` - Projects domain - `taskKeys` - Tasks (dual nature: global and project-scoped) - `knowledgeKeys` - Knowledge base - `progressKeys` - Progress tracking - `documentKeys` - Document management ## Component Naming ### Page Components **Location**: `archon-ui-main/src/pages/` - `[Feature]Page.tsx` - Top-level pages - `[Feature]View.tsx` - Main view components ### Feature Components **Location**: `archon-ui-main/src/features/{feature}/components/` - `[Entity]Card.tsx` - Card displays - `[Entity]List.tsx` - List containers - `[Entity]Form.tsx` - Form components - `New[Entity]Modal.tsx` - Creation modals - `Edit[Entity]Modal.tsx` - Edit modals ### Shared Components **Location**: `archon-ui-main/src/features/ui/primitives/` - Radix UI-based primitives - Generic, reusable components ## State Variable Naming ### Loading States **Examples from**: `archon-ui-main/src/features/projects/views/ProjectsView.tsx` - `isLoading` - Generic loading - `is[Action]ing` - Specific operations (e.g., `isSwitchingProject`) - `[action]ingIds` - Sets of items being processed ### Error States - `error` - Query errors - `[operation]Error` - Specific operation errors ### Selection States - `selected[Entity]` - Currently selected item - `active[Entity]Id` - Active item ID ## Constants and Enums ### Status Values **Location**: `archon-ui-main/src/features/projects/tasks/types/task.ts` Database values used directly - no mapping layers: - Task statuses: `"todo"`, `"doing"`, `"review"`, `"done"` - Operation statuses: `"pending"`, `"processing"`, `"completed"`, `"failed"` ### Time Constants **Location**: `archon-ui-main/src/features/shared/config/queryPatterns.ts` - `STALE_TIMES.instant` - 0ms - `STALE_TIMES.realtime` - 3 seconds - `STALE_TIMES.frequent` - 5 seconds - `STALE_TIMES.normal` - 30 seconds - `STALE_TIMES.rare` - 5 minutes - `STALE_TIMES.static` - Infinity ## File Naming Patterns ### Service Layer - `{feature}Service.ts` - Service modules - Use lower camelCase with "Service" suffix (e.g., `projectService.ts`) ### Hook Files - `use{Feature}Queries.ts` - Query hooks and keys - `use{Feature}.ts` - Feature-specific hooks ### Type Files - `index.ts` - Barrel exports - `{entity}.ts` - Specific entity types ### Test Files - `{filename}.test.ts` - Unit tests - Located in `tests/` subdirectories ## Best Practices ### Do Follow - Use exact database values (no translation layers) - Keep consistent patterns within features - Use query key factories for all cache operations - Follow vertical slice architecture - Reference shared constants ### Don't Do - Don't create mapping layers for database values - Don't hardcode time values - Don't mix query keys between features - Don't use inconsistent naming within a feature - Don't embed business logic in components ## Common Patterns Reference For implementation examples, see: - Query patterns: Any `use{Feature}Queries.ts` file - Service patterns: Any `{feature}Service.ts` file - Type patterns: Any `{feature}/types/` directory - Component patterns: Any `{feature}/components/` directory ================================================ FILE: PRPs/ai_docs/ARCHITECTURE.md ================================================ # Archon Architecture ## Overview Archon is a knowledge management system with AI capabilities, built as a monolithic application with vertical slice organization. The frontend uses React with TanStack Query, while the backend runs FastAPI with multiple service components. ## Tech Stack **Frontend**: React 18, TypeScript 5, TanStack Query v5, Tailwind CSS, Vite **Backend**: Python 3.12, FastAPI, Supabase, PydanticAI **Infrastructure**: Docker, PostgreSQL + pgvector ## Directory Structure ### Backend (`python/src/`) ```text server/ # Main FastAPI application ├── api_routes/ # HTTP endpoints ├── services/ # Business logic ├── models/ # Data models ├── config/ # Configuration ├── middleware/ # Request processing └── utils/ # Shared utilities mcp_server/ # MCP server for IDE integration └── features/ # MCP tool implementations agents/ # AI agents (PydanticAI) └── features/ # Agent capabilities ``` ### Frontend (`archon-ui-main/src/`) ```text features/ # Vertical slice architecture ├── knowledge/ # Knowledge base feature ├── projects/ # Project management │ ├── tasks/ # Task sub-feature │ └── documents/ # Document sub-feature ├── progress/ # Operation tracking ├── mcp/ # MCP integration ├── shared/ # Cross-feature utilities └── ui/ # UI components & hooks pages/ # Route components components/ # Legacy components (migrating) ``` ## Core Modules ### Knowledge Management **Backend**: `python/src/server/services/knowledge_service.py` **Frontend**: `archon-ui-main/src/features/knowledge/` **Features**: Web crawling, document upload, embeddings, RAG search ### Project Management **Backend**: `python/src/server/services/project_*_service.py` **Frontend**: `archon-ui-main/src/features/projects/` **Features**: Projects, tasks, documents, version history ### MCP Server **Location**: `python/src/mcp_server/` **Purpose**: Exposes tools to AI IDEs (Cursor, Windsurf) **Port**: 8051 ### AI Agents **Location**: `python/src/agents/` **Purpose**: Document processing, code analysis, project generation **Port**: 8052 ### Agent Work Orders (Optional) **Location**: `python/src/agent_work_orders/` **Purpose**: Workflow execution engine using Claude Code CLI **Port**: 8053 ## API Structure ### RESTful Endpoints Pattern: `{METHOD} /api/{resource}/{id?}/{sub-resource?}` **Examples from** `python/src/server/api_routes/`: - `/api/projects` - CRUD operations - `/api/projects/{id}/tasks` - Nested resources - `/api/knowledge/search` - RAG search - `/api/progress/{id}` - Operation status ### Service Layer **Pattern**: `python/src/server/services/{feature}_service.py` - Handles business logic - Database operations via Supabase client - Returns typed responses ## Frontend Architecture ### Data Fetching **Core**: TanStack Query v5 **Configuration**: `archon-ui-main/src/features/shared/config/queryClient.ts` **Patterns**: `archon-ui-main/src/features/shared/config/queryPatterns.ts` ### State Management - **Server State**: TanStack Query - **UI State**: React hooks & context - **No Redux/Zustand**: Query cache handles all data ### Feature Organization Each feature follows vertical slice pattern: ```text features/{feature}/ ├── components/ # UI components ├── hooks/ # Query hooks & keys ├── services/ # API calls └── types/ # TypeScript types ``` ### Smart Polling **Implementation**: `archon-ui-main/src/features/ui/hooks/useSmartPolling.ts` - Visibility-aware (pauses when tab hidden) - Variable intervals based on focus state ## Database **Provider**: Supabase (PostgreSQL + pgvector) **Client**: `python/src/server/config/database.py` ### Main Tables - `sources` - Knowledge sources - `documents` - Document chunks with embeddings - `code_examples` - Extracted code - `archon_projects` - Projects - `archon_tasks` - Tasks - `archon_document_versions` - Version history ## Key Architectural Decisions ### Vertical Slices Features own their entire stack (UI → API → DB). See any `features/{feature}/` directory. ### No WebSockets HTTP polling with smart intervals. ETag caching reduces bandwidth by ~70%. ### Query-First State TanStack Query is the single source of truth. No separate state management needed. ### Direct Database Values No translation layers. Database values (e.g., `"todo"`, `"doing"`) used directly in UI. ### Browser-Native Caching ETags handled by browser, not JavaScript. See `archon-ui-main/src/features/shared/api/apiClient.ts`. ## Deployment ### Development ```bash # Backend docker compose up -d # or cd python && uv run python -m src.server.main # Frontend cd archon-ui-main && npm run dev ``` ### Production Single Docker Compose deployment with all services. ## Configuration ### Environment Variables **Required**: `SUPABASE_URL`, `SUPABASE_SERVICE_KEY` **Optional**: See `.env.example` ### Feature Flags Controlled via Settings UI. Projects feature can be disabled. ## Recent Refactors (Phases 1-5) 1. **Removed ETag cache layer** - Browser handles HTTP caching 2. **Standardized query keys** - Each feature owns its keys 3. **Fixed optimistic updates** - UUID-based with nanoid 4. **Configured deduplication** - Centralized QueryClient 5. **Removed manual invalidations** - Trust backend consistency ## Performance Optimizations - **Request Deduplication**: Same query key = one request - **Smart Polling**: Adapts to tab visibility - **ETag Caching**: 70% bandwidth reduction - **Optimistic Updates**: Instant UI feedback ## Testing **Frontend Tests**: `archon-ui-main/src/features/*/tests/` **Backend Tests**: `python/tests/` **Patterns**: Mock services and query patterns, not implementation ## Future Considerations - Server-Sent Events for real-time updates - GraphQL for selective field queries - Separate databases per bounded context - Multi-tenant support ================================================ FILE: PRPs/ai_docs/DATA_FETCHING_ARCHITECTURE.md ================================================ # Data Fetching Architecture ## Overview Archon uses **TanStack Query v5** for all data fetching, caching, and synchronization. This replaces the former custom polling layer with a query‑centric design that handles caching, deduplication, and smart refetching (including visibility‑aware polling) automatically. ## Core Components ### 1. Query Client Configuration **Location**: `archon-ui-main/src/features/shared/config/queryClient.ts` Centralized QueryClient with: - 30-second default stale time - 10-minute garbage collection - Smart retry logic (skips 4xx errors) - Request deduplication enabled - Structural sharing for optimized re-renders ### 2. Smart Polling Hook **Location**: `archon-ui-main/src/features/ui/hooks/useSmartPolling.ts` Visibility-aware polling that: - Pauses when browser tab is hidden - Slows down (1.5x interval) when tab is unfocused - Returns `refetchInterval` for use with TanStack Query ### 3. Query Patterns **Location**: `archon-ui-main/src/features/shared/config/queryPatterns.ts` Shared constants: - `DISABLED_QUERY_KEY` - For disabled queries - `STALE_TIMES` - Standardized cache durations (instant, realtime, frequent, normal, rare, static) ## Feature Implementation Patterns ### Query Key Factories Each feature maintains its own query keys: - **Projects**: `archon-ui-main/src/features/projects/hooks/useProjectQueries.ts` (projectKeys) - **Tasks**: `archon-ui-main/src/features/projects/tasks/hooks/useTaskQueries.ts` (taskKeys) - **Knowledge**: `archon-ui-main/src/features/knowledge/hooks/useKnowledgeQueries.ts` (knowledgeKeys) - **Progress**: `archon-ui-main/src/features/progress/hooks/useProgressQueries.ts` (progressKeys) - **MCP**: `archon-ui-main/src/features/mcp/hooks/useMcpQueries.ts` (mcpKeys) - **Documents**: `archon-ui-main/src/features/projects/documents/hooks/useDocumentQueries.ts` (documentKeys) ### Data Fetching Hooks Standard pattern across all features: - `use[Feature]()` - List queries - `use[Feature]Detail(id)` - Single item queries - `useCreate[Feature]()` - Creation mutations - `useUpdate[Feature]()` - Update mutations - `useDelete[Feature]()` - Deletion mutations ## Backend Integration ### ETag Support **Location**: `archon-ui-main/src/features/shared/api/apiClient.ts` ETag implementation: - Browser handles ETag headers automatically - 304 responses reduce bandwidth - TanStack Query manages cache state ### API Structure Backend endpoints follow RESTful patterns: - **Knowledge**: `python/src/server/api_routes/knowledge_api.py` - **Projects**: `python/src/server/api_routes/projects_api.py` - **Progress**: `python/src/server/api_routes/progress_api.py` - **MCP**: `python/src/server/api_routes/mcp_api.py` ## Optimistic Updates **Utilities**: `archon-ui-main/src/features/shared/utils/optimistic.ts` All mutations use nanoid-based optimistic updates: - Creates temporary entities with `_optimistic` flag - Replaces with server data on success - Rollback on error - Visual indicators for pending state ## Refetch Strategies ### Smart Polling Usage **Implementation**: `archon-ui-main/src/features/ui/hooks/useSmartPolling.ts` Polling intervals are defined in each feature's query hooks. See actual implementations: - **Projects**: `archon-ui-main/src/features/projects/hooks/useProjectQueries.ts` - **Tasks**: `archon-ui-main/src/features/projects/tasks/hooks/useTaskQueries.ts` - **Knowledge**: `archon-ui-main/src/features/knowledge/hooks/useKnowledgeQueries.ts` - **Progress**: `archon-ui-main/src/features/progress/hooks/useProgressQueries.ts` - **MCP**: `archon-ui-main/src/features/mcp/hooks/useMcpQueries.ts` Standard intervals from `archon-ui-main/src/features/shared/config/queryPatterns.ts`: - `STALE_TIMES.instant`: 0ms (always fresh) - `STALE_TIMES.frequent`: 5 seconds (frequently changing data) - `STALE_TIMES.normal`: 30 seconds (standard cache) ### Manual Refetch All queries expose `refetch()` for manual updates. ## Performance Optimizations ### Request Deduplication Handled automatically by TanStack Query when same query key is used. ### Stale Time Configuration Defined in `STALE_TIMES` and used consistently: - Auth/Settings: `Infinity` (never stale) - Active operations: `0` (always fresh) - Normal data: `30_000` (30 seconds) - Rare updates: `300_000` (5 minutes) ### Garbage Collection Unused data removed after 10 minutes (configurable in queryClient). ## Migration from Polling ### What Changed (Phases 1-5) 1. **Phase 1**: Removed ETag cache layer 2. **Phase 2**: Standardized query keys 3. **Phase 3**: Fixed optimistic updates with UUIDs 4. **Phase 4**: Configured request deduplication 5. **Phase 5**: Removed manual invalidations ### Deprecated Patterns - `usePolling` hook (removed) - `useCrawlProgressPolling` (removed) - Manual cache invalidation with setTimeout - Socket.IO connections - Double-layer caching ## Testing Patterns ### Hook Testing **Example**: `archon-ui-main/src/features/projects/hooks/tests/useProjectQueries.test.ts` Standard mocking approach for: - Service methods - Query patterns (STALE_TIMES, DISABLED_QUERY_KEY) - Smart polling behavior ### Integration Testing Use React Testing Library with QueryClientProvider wrapper. ## Developer Guidelines ### Adding New Data Fetching 1. Create query key factory in `{feature}/hooks/use{Feature}Queries.ts` 2. Use `useQuery` with appropriate stale time from `STALE_TIMES` 3. Add smart polling if real-time updates needed 4. Implement optimistic updates for mutations 5. Follow existing patterns in similar features ### Common Patterns to Follow - Always use query key factories - Never hardcode stale times - Use `DISABLED_QUERY_KEY` for conditional queries - Implement optimistic updates for better UX - Add loading and error states ## Future Considerations - Server-Sent Events for true real-time (post-Phase 5) - WebSocket fallback for critical updates - GraphQL migration for selective field updates ================================================ FILE: PRPs/ai_docs/ETAG_IMPLEMENTATION.md ================================================ # ETag Implementation ## Overview Archon implements HTTP ETag caching to optimize bandwidth usage by reducing redundant data transfers. The implementation leverages browser-native HTTP caching combined with backend ETag generation for efficient cache validation. ## How It Works ### Backend ETag Generation **Location**: `python/src/server/utils/etag_utils.py` The backend generates ETags for API responses: - Creates MD5 hash of JSON-serialized response data - Returns quoted ETag string (RFC 7232 format) - Sets `Cache-Control: no-cache, must-revalidate` headers - Compares client's `If-None-Match` header with current data's ETag - Returns `304 Not Modified` when ETags match ### Frontend Handling **Location**: `archon-ui-main/src/features/shared/api/apiClient.ts` The frontend relies on browser-native HTTP caching: - Browser automatically sends `If-None-Match` headers with cached ETags - Browser handles 304 responses by returning cached data from HTTP cache - No manual ETag tracking or cache management needed - TanStack Query manages data freshness through `staleTime` configuration #### Browser vs Non-Browser Behavior - **Standard Browsers**: Per the Fetch spec, a 304 response freshens the HTTP cache and returns the cached body to JavaScript - **Non-Browser Runtimes** (React Native, custom fetch): May surface 304 with empty body to JavaScript - **Client Fallback**: The `apiClient.ts` implementation handles both scenarios, ensuring consistent behavior across environments ## Implementation Details ### Backend API Integration ETags are used in these API routes: - **Projects**: `python/src/server/api_routes/projects_api.py` - Project lists - Task lists - Task counts - **Progress**: `python/src/server/api_routes/progress_api.py` - Active operations tracking ### ETag Generation Process 1. **Data Serialization**: Response data is JSON-serialized with sorted keys for consistency 2. **Hash Creation**: MD5 hash generated from JSON string 3. **Format**: Returns quoted string per RFC 7232 (e.g., `"a3c2f1e4b5d6789"`) ### Cache Validation Flow 1. **Initial Request**: Server generates ETag and sends with response 2. **Subsequent Requests**: Browser sends `If-None-Match` header with cached ETag 3. **Server Validation**: - ETags match → Returns `304 Not Modified` (no body) - ETags differ → Returns `200 OK` with new data and new ETag 4. **Browser Behavior**: On 304, browser serves cached response to JavaScript ## Key Design Decisions ### Browser-Native Caching The implementation leverages browser HTTP caching instead of manual cache management: - Reduces code complexity - Eliminates cache synchronization issues - Works seamlessly with TanStack Query - Maintains bandwidth optimization ### No Manual ETag Tracking Unlike previous implementations, the current approach: - Does NOT maintain ETag maps in JavaScript - Does NOT manually handle 304 responses - Lets browser and TanStack Query handle caching layers ## Integration with TanStack Query ### Cache Coordination - **Browser Cache**: Handles HTTP-level caching (ETags/304s) - **TanStack Query Cache**: Manages application-level data freshness - **Separation of Concerns**: HTTP caching for bandwidth, TanStack for state ### Configuration Cache behavior is controlled through TanStack Query's `staleTime`: - See `archon-ui-main/src/features/shared/config/queryPatterns.ts` for standard times - See `archon-ui-main/src/features/shared/config/queryClient.ts` for global configuration ## Performance Benefits ### Bandwidth Reduction - ~70% reduction in data transfer for unchanged responses (based on internal measurements) - Especially effective for polling patterns - Significant improvement for mobile/slow connections ### Server Load - Reduced JSON serialization for 304 responses - Lower network I/O - Faster response times for cached data ## Files and References ### Core Implementation - **Backend Utilities**: `python/src/server/utils/etag_utils.py` - **Frontend Client**: `archon-ui-main/src/features/shared/api/apiClient.ts` - **Tests**: `python/tests/server/utils/test_etag_utils.py` ### Usage Examples - **Projects API**: `python/src/server/api_routes/projects_api.py` (lines with `generate_etag`, `check_etag`) - **Progress API**: `python/src/server/api_routes/progress_api.py` (active operations tracking) ## Testing ### Backend Testing Tests in `python/tests/server/utils/test_etag_utils.py` verify: - Correct ETag generation format - Consistent hashing for same data - Different hashes for different data - Proper quote formatting ### Frontend Testing Browser DevTools verification: 1. Network tab shows `If-None-Match` headers on requests 2. 304 responses have no body 3. Response served from cache on 304 4. New ETag values when data changes ## Monitoring ### How to Verify ETags are Working 1. Open Chrome DevTools → Network tab 2. Make a request to a supported endpoint 3. Note the `ETag` response header 4. Refresh or re-request the same data 5. Observe: - Request includes `If-None-Match` header - Server returns `304 Not Modified` if unchanged - Response body is empty on 304 - Browser serves cached data ### Metrics to Track - Ratio of 304 vs 200 responses - Bandwidth saved through 304 responses - Cache hit rate in production ## Future Considerations - Consider implementing strong vs weak ETags for more granular control - Evaluate adding ETag support to more endpoints - Monitor cache effectiveness in production - Consider Last-Modified headers as supplementary validation ================================================ FILE: PRPs/ai_docs/QUERY_PATTERNS.md ================================================ # TanStack Query Patterns Guide This guide documents the standardized patterns for using TanStack Query v5 in the Archon frontend. ## Core Principles 1. **Feature Ownership**: Each feature owns its query keys in `{feature}/hooks/use{Feature}Queries.ts` 2. **Consistent Patterns**: Always use shared patterns from `shared/config/queryPatterns.ts` 3. **No Hardcoded Values**: Never hardcode stale times or disabled keys 4. **Mirror Backend API**: Query keys should exactly match backend API structure ## Query Key Factory Pattern Every feature MUST implement a query key factory following this pattern: ```typescript // features/{feature}/hooks/use{Feature}Queries.ts export const featureKeys = { all: ["feature"] as const, // Base key for the domain lists: () => [...featureKeys.all, "list"] as const, // For list endpoints detail: (id: string) => [...featureKeys.all, "detail", id] as const, // For single item // Add more as needed following backend routes }; ``` ### Examples from Codebase ```typescript // Projects - Simple hierarchy export const projectKeys = { all: ["projects"] as const, lists: () => [...projectKeys.all, "list"] as const, detail: (id: string) => [...projectKeys.all, "detail", id] as const, features: (id: string) => [...projectKeys.all, id, "features"] as const, }; // Tasks - Dual nature (global and project-scoped) export const taskKeys = { all: ["tasks"] as const, lists: () => [...taskKeys.all, "list"] as const, // /api/tasks detail: (id: string) => [...taskKeys.all, "detail", id] as const, byProject: (projectId: string) => ["projects", projectId, "tasks"] as const, // /api/projects/{id}/tasks counts: () => [...taskKeys.all, "counts"] as const, }; ``` ## Shared Patterns Usage ### Import Required Patterns ```typescript import { DISABLED_QUERY_KEY, STALE_TIMES } from "@/features/shared/config/queryPatterns"; ``` ### Disabled Queries Always use `DISABLED_QUERY_KEY` when a query should not execute: ```typescript // ✅ CORRECT queryKey: projectId ? projectKeys.detail(projectId) : DISABLED_QUERY_KEY, // ❌ WRONG - Don't create custom disabled keys queryKey: projectId ? projectKeys.detail(projectId) : ["projects-undefined"], ``` ### Stale Times Always use `STALE_TIMES` constants for cache configuration: ```typescript // ✅ CORRECT staleTime: STALE_TIMES.normal, // 30 seconds staleTime: STALE_TIMES.frequent, // 5 seconds staleTime: STALE_TIMES.instant, // 0 - always fresh // ❌ WRONG - Don't hardcode times staleTime: 30000, staleTime: 0, ``` #### STALE_TIMES Reference - `instant: 0` - Always fresh (real-time data like active progress) - `realtime: 3_000` - 3 seconds (near real-time updates) - `frequent: 5_000` - 5 seconds (frequently changing data) - `normal: 30_000` - 30 seconds (standard cache time) - `rare: 300_000` - 5 minutes (rarely changing config) - `static: Infinity` - Never stale (settings, auth) ## Complete Hook Pattern ```typescript export function useFeatureDetail(id: string | undefined) { return useQuery({ queryKey: id ? featureKeys.detail(id) : DISABLED_QUERY_KEY, queryFn: () => id ? featureService.getFeatureById(id) : Promise.reject("No ID provided"), enabled: !!id, staleTime: STALE_TIMES.normal, }); } ``` ## Mutations with Optimistic Updates ```typescript import { createOptimisticEntity, replaceOptimisticEntity } from "@/features/shared/utils/optimistic"; export function useCreateFeature() { const queryClient = useQueryClient(); return useMutation({ mutationFn: (data: CreateFeatureRequest) => featureService.create(data), onMutate: async (newData) => { // Cancel in-flight queries await queryClient.cancelQueries({ queryKey: featureKeys.lists() }); // Snapshot for rollback const previous = queryClient.getQueryData(featureKeys.lists()); // Optimistic update with nanoid for stable IDs const optimisticEntity = createOptimisticEntity(newData); queryClient.setQueryData(featureKeys.lists(), (old: Feature[] = []) => [...old, optimisticEntity] ); return { previous, localId: optimisticEntity._localId }; }, onError: (err, variables, context) => { // Rollback on error if (context?.previous) { queryClient.setQueryData(featureKeys.lists(), context.previous); } }, onSuccess: (data, variables, context) => { // Replace optimistic with real data queryClient.setQueryData(featureKeys.lists(), (old: Feature[] = []) => replaceOptimisticEntity(old, context?.localId, data) ); }, }); } ``` ## Testing Query Hooks Always mock both services and shared patterns: ```typescript // Mock services vi.mock("../../services", () => ({ featureService: { getList: vi.fn(), getById: vi.fn(), }, })); // Mock shared patterns with ALL values vi.mock("../../../shared/config/queryPatterns", () => ({ DISABLED_QUERY_KEY: ["disabled"] as const, STALE_TIMES: { instant: 0, realtime: 3_000, frequent: 5_000, normal: 30_000, rare: 300_000, static: Infinity, }, })); ``` ## Vertical Slice Architecture Each feature is self-contained: ```text src/features/projects/ ├── components/ # UI components ├── hooks/ │ └── useProjectQueries.ts # Query hooks & keys ├── services/ │ └── projectService.ts # API calls └── types/ └── index.ts # TypeScript types ``` Sub-features (like tasks under projects) follow the same structure: ```text src/features/projects/tasks/ ├── components/ ├── hooks/ │ └── useTaskQueries.ts # Own query keys! ├── services/ └── types/ ``` ## Migration Checklist When refactoring to these patterns: - [ ] Create query key factory in `hooks/use{Feature}Queries.ts` - [ ] Import `DISABLED_QUERY_KEY` and `STALE_TIMES` from shared - [ ] Replace all hardcoded disabled keys with `DISABLED_QUERY_KEY` - [ ] Replace all hardcoded stale times with `STALE_TIMES` constants - [ ] Update all `queryKey` references to use factory - [ ] Update all `invalidateQueries` to use factory - [ ] Update all `setQueryData` to use factory - [ ] Add comprehensive tests for query keys - [ ] Remove any backward compatibility code ## Common Pitfalls to Avoid 1. **Don't create centralized query keys** - Each feature owns its keys 2. **Don't hardcode values** - Use shared constants 3. **Don't mix concerns** - Tasks shouldn't import projectKeys 4. **Don't skip mocking in tests** - Mock both services and patterns 5. **Don't use inconsistent patterns** - Follow the established conventions ## Completed Improvements (Phases 1-5) - ✅ Phase 1: Removed manual frontend ETag cache layer (backend ETags remain; browser-managed) - ✅ Phase 2: Standardized query keys with factories - ✅ Phase 3: Implemented UUID-based optimistic updates using nanoid - ✅ Phase 4: Configured request deduplication - ✅ Phase 5: Removed manual cache invalidations ## Future Considerations - Add Server-Sent Events for real-time updates - Consider WebSocket fallback for critical updates - Evaluate Zustand for complex client state management ================================================ FILE: PRPs/ai_docs/UI_STANDARDS.md ================================================ # Archon UI Standards **Audience**: AI agents performing automated UI audits and refactors **Purpose**: Single source of truth for UI patterns, violations, and automated detection **Usage**: Run `/archon:archon-ui-consistency-review` to scan code against these standards --- ## 1. TAILWIND V4 ### Rules - **NO dynamic class construction** - Tailwind scans source code as plain text at build time - NEVER: `` `bg-${color}-500` ``, `` `ring-${color}-500` ``, `` `shadow-${size}` `` - Use static lookup objects instead - **Bare HSL values in CSS variables** - NO `hsl()` wrapper - Correct: `--background: 0 0% 98%;` - Wrong: `--background: hsl(0 0% 98%);` - **CSS variables allowed in arbitrary values** - Utility name must be static - Correct: `bg-[var(--accent)]` - Wrong: `` `bg-[var(--${colorName})]` `` - **Use @theme inline** to map CSS vars to Tailwind utilities - **Define @custom-variant dark** - Required for `dark:` to work in v4 ### Anti-Patterns ```tsx // ❌ Dynamic classes (NO CSS GENERATED) const color = "cyan";
// Common miss! // ❌ Inline styles for visual CSS
``` ### Good Examples ```tsx // ✅ Static lookup for discrete variants const colorClasses = { cyan: "bg-cyan-500 text-cyan-900 ring-cyan-500", purple: "bg-purple-500 text-purple-900 ring-purple-500", };
// ✅ CSS variables for dynamic values
``` ### Automated Scans ```bash # All dynamic class construction patterns grep -rn "className.*\`.*\${.*}\`" [path] --include="*.tsx" grep -rn "bg-\${.*}\|text-\${.*}\|border-\${.*}" [path] --include="*.tsx" grep -rn "ring-\${.*}\|shadow-\${.*}\|outline-\${.*}\|opacity-\${.*}" [path] --include="*.tsx" # Inline visual styles (not CSS vars) grep -rn "style={{.*backgroundColor\|color:\|padding:" [path] --include="*.tsx" ``` **Fix Pattern**: Add all properties to static variant object (checked, glow, focusRing, hover) --- ## 2. LAYOUT & RESPONSIVE ### Rules - **Responsive grids** - NEVER fixed columns without breakpoints - Use: `grid-cols-1 md:grid-cols-2 lg:grid-cols-4` - **Constrain horizontal scroll** - Parent must have `w-full` or `max-w-*` - **Add scrollbar-hide** to all `overflow-x-auto` containers - **min-w-0 on flex parents** containing scroll containers (prevents page expansion) - **Text truncation** - Always use `truncate`, `line-clamp-N`, or `break-words` - **Desktop-primary** - Optimize for desktop, add responsive breakpoints down ### Anti-Patterns ```tsx // ❌ Fixed grid (breaks mobile)
// ❌ Unconstrained scroll (page becomes horizontally scrollable)
// ❌ Flex parent without min-w-0 (page expansion)
{/* MISSING min-w-0! */}
``` ### Good Examples ```tsx // ✅ Responsive grid
// ✅ Constrained horizontal scroll
// ✅ Flex parent with scroll container
{/* min-w-0 CRITICAL */} ``` ### Automated Scans ```bash # Non-responsive grids grep -rn "grid-cols-[2-9]" [path] --include="*.tsx" | grep -v "md:\|lg:\|xl:" # Unconstrained scroll grep -rn "overflow-x-auto" [path] --include="*.tsx" # Then manually verify parent has w-full # Missing text truncation grep -rn "`, add responsive breakpoints to grids --- ## 3. THEMING ### Rules - **Every visible color needs `dark:` variant** - **Structure identical** between themes (only colors/opacity change) - **Use tokens** for both light and dark (`--bg` and redefine in `.dark`) ### Anti-Patterns ```tsx // ❌ No dark variant
// ❌ Different structure in dark mode {theme === 'dark' ? : } ``` ### Good Examples ```tsx // ✅ Both themes
``` ### Automated Scans ```bash # Colors without dark variants grep -rn "bg-.*-[0-9]" [path] --include="*.tsx" | grep -v "dark:" ``` **Fix Pattern**: Add `dark:` variant for every color, border, shadow --- ## 4. RADIX UI ### Rules - **Use Radix primitives** - NEVER native ``, `` - **Compose with asChild** - Don't wrap, attach behavior to your components - **Style via data attributes** - `[data-state="open"]`, `[data-disabled]` - **Use Portal** for overlays with proper z-index - **Support both controlled and uncontrolled modes** - All form primitives must work in both modes ### Controlled vs Uncontrolled Form Components **CRITICAL RULE**: Form primitives (Switch, Checkbox, Select, etc.) MUST support both controlled and uncontrolled modes. **Controlled Mode**: Parent manages state via `value`/`checked` prop + `onChange`/`onCheckedChange` handler **Uncontrolled Mode**: Component manages own state via `defaultValue`/`defaultChecked` ### Anti-Patterns ```tsx // ❌ Native HTML // ❌ Wrong composition // ❌ Only supports controlled mode (breaks uncontrolled usage) const Switch = ({ checked, ...props }) => { const displayIcon = checked ? iconOn : iconOff; // No internal state! return }; ``` ### Good Examples ```tsx // ✅ Radix with asChild // ✅ Radix primitives // ✅ Supports both controlled and uncontrolled modes const Switch = ({ checked, defaultChecked, onCheckedChange, ...props }) => { const isControlled = checked !== undefined; const [internalChecked, setInternalChecked] = useState(defaultChecked ?? false); const actualChecked = isControlled ? checked : internalChecked; const handleChange = (newChecked: boolean) => { if (!isControlled) setInternalChecked(newChecked); onCheckedChange?.(newChecked); }; return }; ``` ### Automated Scans ```bash # Native HTML form elements grep -rn "\|type=\"checkbox\"" [path]` - Emerald usage: `grep -rn "emerald" [path] --include="*.tsx" --include="*.ts"` (must use "green") ### High Priority - Missing keyboard: `grep -rn "onClick.*role=\"button\"" [path]` (verify onKeyDown) - Clickable icons: `grep -rn "<[A-Z].*onClick={" [path] --include="*.tsx" | grep -v "&1 | grep "error TS"` - Line length: `grep -rn ".\{121,\}" [path] --include="*.tsx" | grep className` - Missing satisfies: `grep -rn "const.*Classes = {" [path]/primitives -A 5 | grep -v "satisfies"` - Props unused: Manual check interfaces vs usage --- ## QUICK REFERENCE ### Breakpoints - sm: 640px | md: 768px | lg: 1024px | xl: 1280px | 2xl: 1536px ### Color Variant Checklist (for primitives with colors) Every color object MUST have: - [ ] `checked` or `active` state classes - [ ] `glow` effect - [ ] `focusRing` - STATIC class like `"focus-visible:ring-cyan-500"` - [ ] `hover` state - [ ] All 6 colors: purple, blue, cyan, green, orange, pink ### Common Patterns **Horizontal Scroll (Archon Standard)** ```tsx
{items.map(i => )} ``` **Responsive Grid** ```tsx
``` **Flex + Scroll Container** ```tsx
{/* min-w-0 REQUIRED */} {/* scroll containers here */} ``` **Color Variants (Static Lookup)** ```tsx const variants = { cyan: { checked: "data-[state=checked]:bg-cyan-500/20", glow: "shadow-[0_0_15px_rgba(34,211,238,0.5)]", focusRing: "focus-visible:ring-cyan-500", // STATIC! hover: "hover:bg-cyan-500/10", }, // ... repeat for all colors }; ``` **Keyboard Support** ```tsx
(e.key === "Enter" || e.key === " ") && handler()} aria-selected={isSelected} > ``` --- ## SCORING VIOLATIONS ### Critical (-3 points each) - Dynamic class construction - Missing keyboard support on interactive - Non-responsive grids causing horizontal scroll - TypeScript errors ### High (-2 points each) - Unconstrained scroll containers - Props that do nothing - Non-functional UI logic (filter/sort/drag-drop) - Missing dark mode variants ### Medium (-1 point each) - Native HTML form elements - Hardcoded glassmorphism - Missing text truncation - Color type inconsistencies **Grading Scale:** - 0 critical violations: A (9-10/10) - 1 critical: B (7-8/10) - 2-3 critical: C (5-6/10) - 4+ critical: F (1-4/10) --- ## ADDING NEW RULES When code review finds an issue not caught by automated review: 1. **Identify which section** it belongs to (Tailwind? Layout? A11y?) 2. **Add to that section**: - Rule (what to do) - Anti-Pattern example - Good example - Automated scan (if possible) 3. **Add scan to AUTOMATED SCAN REFERENCE** 4. **Done** - Next review will catch it **Goal**: Eventually eliminate manual code reviews entirely. ================================================ FILE: PRPs/ai_docs/ZUSTAND_STATE_MANAGEMENT.md ================================================ Zustand v4 AI Coding Assistant Standards Purpose These guidelines define how an AI coding assistant should generate, refactor, and reason about Zustand (v4) state management code. They serve as enforceable standards to ensure clarity, consistency, maintainability, and performance across all code suggestions. ⸻ 1. General Rules • Use TypeScript for all Zustand stores. • All stores must be defined with the create() function from Zustand v4. • State must be immutable; never mutate arrays or objects directly. • Use functional updates with set((state) => ...) whenever referencing existing state. • Never use useStore.getState() inside React render logic. ⸻ 2. Store Creation Rules Do: import { create } from 'zustand'; type CounterStore = { count: number; increment: () => void; reset: () => void; }; export const useCounterStore = create((set) => ({ count: 0, increment: () => set((state) => ({ count: state.count + 1 })), reset: () => set({ count: 0 }) })); Don’t: • Define stores inline within components. • Create multiple stores for related state when a single one suffices. • Nest stores inside hooks or conditional logic. Naming conventions: • Hook: useStore (e.g., useUserStore, useThemeStore). • File: same as hook (e.g., useUserStore.ts). ⸻ 3. Store Organization Rules • Each feature (e.g., agent-work-orders, knowledge, settings, etc..) should have its own store file. • Combine complex stores using slices, not nested state. • Use middleware (persist, devtools, immer) only when necessary. Example structure: src/features/knowledge/state/ ├── knowledgeStore.ts └── slices/ #If necessary ├── nameSlice.ts #a name that represents the slice if needed ⸻ 4. Selector and Subscription Rules Core Principle: Components should subscribe only to the exact slice of state they need. Do: const count = useCounterStore((s) => s.count); const increment = useCounterStore((s) => s.increment); Don’t: const { count, increment } = useCounterStore(); // ❌ Causes unnecessary re-renders Additional rules: • Use shallow comparison (shallow) if selecting multiple fields. • Avoid subscribing to derived values that can be computed locally. ⸻ 5. Middleware and Side Effects Allowed middleware: persist, devtools, immer, subscribeWithSelector. Rules: • Never persist volatile or sensitive data (e.g., tokens, temp state). • Configure partialize to persist only essential state. • Guard devtools with environment checks. Example: import { create } from 'zustand'; import { persist, devtools } from 'zustand/middleware'; export const useSettingsStore = create( devtools( persist( (set) => ({ theme: 'light', toggleTheme: () => set((s) => ({ theme: s.theme === 'light' ? 'dark' : 'light' })) }), { name: 'settings-store', partialize: (state) => ({ theme: state.theme }) } ) ) ); ⸻ 6. Async Logic Rules • Async actions should be defined inside the store. • Avoid direct useEffect calls that depend on store state. Do: fetchData: async () => { const data = await api.getData(); set({ data }); } Don’t: useEffect(() => { useStore.getState().fetchData(); // ❌ Side effect in React hook }, []); ⸻ 7. Anti-Patterns ❌ Anti-Pattern 🚫 Reason Subscribing to full store Causes unnecessary re-renders Inline store creation in component Breaks referential integrity Mutating state directly Zustand expects immutability Business logic inside components Should live in store actions Using store for local-only UI state Clutters global state Multiple independent stores for one domain Increases complexity ⸻ 8. Testing Rules • Each store must be testable as a pure function. • Tests should verify: initial state, action side effects, and immutability. Example Jest test: import { useCounterStore } from '../state/useCounterStore'; test('increment increases count', () => { const { increment, count } = useCounterStore.getState(); increment(); expect(useCounterStore.getState().count).toBe(count + 1); }); ⸻ 9. Documentation Rules • Every store file must include: • Top-level JSDoc summarizing store purpose. • Type definitions for state and actions. • Examples for consumption patterns. • Maintain a STATE_GUIDELINES.md index in the repo root linking all store docs. ⸻ 10. Enforcement Summary (AI Assistant Logic) When generating Zustand code: • ALWAYS define stores with create() at module scope. • NEVER create stores inside React components. • ALWAYS use selectors in components. • AVOID getState() in render logic. • PREFER shallow comparison for multiple subscriptions. • LIMIT middleware to proven cases (persist, devtools, immer). • TEST every action in isolation. • DOCUMENT store purpose, shape, and actions. ⸻ # Zustand v3 → v4 Summary (for AI Coding Assistants) ## Overview Zustand v4 introduced a few key syntax and type changes focused on improving TypeScript inference, middleware chaining, and internal consistency. All existing concepts (store creation, selectors, middleware, subscriptions) remain — only the *patterns* and *type structure* changed. --- ## Core Concept Changes - **Curried Store Creation:** `create()` now expects a *curried call* form when using generics or middleware. The previous single-call pattern is deprecated. - **TypeScript Inference Improvements:** v4’s curried syntax provides stronger type inference for complex stores and middleware combinations. - **Stricter Generic Typing:** Functions like `set`, `get`, and the store API have tighter TypeScript types. Any implicit `any` usage or loosely typed middleware will now error until corrected. --- ## Middleware Updates - Middleware is still supported but must be imported from subpaths (e.g., `zustand/middleware/immer`). - The structure of most built-in middlewares (persist, devtools, immer, subscribeWithSelector) remains identical. - Chaining multiple middlewares now depends on the curried `create` syntax for correct type inference. --- ## Persistence and Migration - `persist` behavior is unchanged functionally, but TypeScript typing for the `migrate` function now defines the input state as `unknown`. You must assert or narrow this type when using TypeScript. - The `name`, `version`, and other options are unchanged. --- ## Type Adjustments - The `set` function now includes a `replace` parameter for full state replacement. - `get` and `api` generics are explicitly typed and must align with the store definition. - Custom middleware and typed stores may need to specify generic parameters to avoid inference gaps. --- ## Behavior and API Consistency - Core APIs like `getState()`, `setState()`, and `subscribe()` are still valid. - Hook usage (`useStore(state => state.value)`) is identical. - Differences are primarily at compile time (typing), not runtime. --- ## Migration/Usage Implications For AI agents generating Zustand code: - Always use the **curried `create()(…)`** pattern when defining stores. - Always import middleware from `zustand/middleware/...`. - Expect `set`, `get`, and `api` to have stricter typings. - Assume `migrate` in persistence returns `unknown` and must be asserted. - Avoid any v3-style `create(fn)` calls. - Middleware chaining depends on the curried syntax — never use nested functions without it. --- ## Reference Behavior - Functional concepts are unchanged: stores, actions, and reactivity all behave the same. - Only the declaration pattern and TypeScript inference system differ. --- ## Summary | Area | Zustand v3 | Zustand v4 | |------|-------------|------------| | Store creation | Single function call | Curried two-step syntax | | TypeScript inference | Looser | Stronger, middleware-aware | | Middleware imports | Flat path | Sub-path imports | | Migrate typing | `any` | `unknown` | | API methods | Same | Same, stricter typing | | Runtime behavior | Same | Same | --- ## Key Principle for Code Generation > “If defining a store, always use the curried `create()` syntax, import middleware from subpaths, and respect stricter generics. All functional behavior remains identical to v3.” --- **Recommended Source:** [Zustand v4 Migration Guide – Official Docs](https://zustand.docs.pmnd.rs/migrations/migrating-to-v4) ================================================ FILE: PRPs/ai_docs/cc_cli_ref.md ================================================ # CLI reference > Complete reference for Claude Code command-line interface, including commands and flags. ## CLI commands | Command | Description | Example | | :--------------------------------- | :--------------------------------------------- | :----------------------------------------------------------------- | | `claude` | Start interactive REPL | `claude` | | `claude "query"` | Start REPL with initial prompt | `claude "explain this project"` | | `claude -p "query"` | Query via SDK, then exit | `claude -p "explain this function"` | | `cat file \| claude -p "query"` | Process piped content | `cat logs.txt \| claude -p "explain"` | | `claude -c` | Continue most recent conversation | `claude -c` | | `claude -c -p "query"` | Continue via SDK | `claude -c -p "Check for type errors"` | | `claude -r "" "query"` | Resume session by ID | `claude -r "abc123" "Finish this PR"` | | `claude update` | Update to latest version | `claude update` | | `claude mcp` | Configure Model Context Protocol (MCP) servers | See the [Claude Code MCP documentation](/en/docs/claude-code/mcp). | ## CLI flags Customize Claude Code's behavior with these command-line flags: | Flag | Description | Example | | :------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------- | | `--add-dir` | Add additional working directories for Claude to access (validates each path exists as a directory) | `claude --add-dir ../apps ../lib` | | `--agents` | Define custom [subagents](/en/docs/claude-code/sub-agents) dynamically via JSON (see below for format) | `claude --agents '{"reviewer":{"description":"Reviews code","prompt":"You are a code reviewer"}}'` | | `--allowedTools` | A list of tools that should be allowed without prompting the user for permission, in addition to [settings.json files](/en/docs/claude-code/settings) | `"Bash(git log:*)" "Bash(git diff:*)" "Read"` | | `--disallowedTools` | A list of tools that should be disallowed without prompting the user for permission, in addition to [settings.json files](/en/docs/claude-code/settings) | `"Bash(git log:*)" "Bash(git diff:*)" "Edit"` | | `--print`, `-p` | Print response without interactive mode (see [SDK documentation](/en/docs/claude-code/sdk) for programmatic usage details) | `claude -p "query"` | | `--append-system-prompt` | Append to system prompt (only with `--print`) | `claude --append-system-prompt "Custom instruction"` | | `--output-format` | Specify output format for print mode (options: `text`, `json`, `stream-json`) | `claude -p "query" --output-format json` | | `--input-format` | Specify input format for print mode (options: `text`, `stream-json`) | `claude -p --output-format json --input-format stream-json` | | `--include-partial-messages` | Include partial streaming events in output (requires `--print` and `--output-format=stream-json`) | `claude -p --output-format stream-json --include-partial-messages "query"` | | `--verbose` | Enable verbose logging, shows full turn-by-turn output (helpful for debugging in both print and interactive modes) | `claude --verbose` | | `--max-turns` | Limit the number of agentic turns in non-interactive mode | `claude -p --max-turns 3 "query"` | | `--model` | Sets the model for the current session with an alias for the latest model (`sonnet` or `opus`) or a model's full name | `claude --model claude-sonnet-4-5-20250929` | | `--permission-mode` | Begin in a specified [permission mode](iam#permission-modes) | `claude --permission-mode plan` | | `--permission-prompt-tool` | Specify an MCP tool to handle permission prompts in non-interactive mode | `claude -p --permission-prompt-tool mcp_auth_tool "query"` | | `--resume` | Resume a specific session by ID, or by choosing in interactive mode | `claude --resume abc123 "query"` | | `--continue` | Load the most recent conversation in the current directory | `claude --continue` | | `--dangerously-skip-permissions` | Skip permission prompts (use with caution) | `claude --dangerously-skip-permissions` | The `--output-format json` flag is particularly useful for scripting and automation, allowing you to parse Claude's responses programmatically. ### Agents flag format The `--agents` flag accepts a JSON object that defines one or more custom subagents. Each subagent requires a unique name (as the key) and a definition object with the following fields: | Field | Required | Description | | :------------ | :------- | :-------------------------------------------------------------------------------------------------------------- | | `description` | Yes | Natural language description of when the subagent should be invoked | | `prompt` | Yes | The system prompt that guides the subagent's behavior | | `tools` | No | Array of specific tools the subagent can use (e.g., `["Read", "Edit", "Bash"]`). If omitted, inherits all tools | | `model` | No | Model alias to use: `sonnet`, `opus`, or `haiku`. If omitted, uses the default subagent model | Example: ```bash theme={null} claude --agents '{ "code-reviewer": { "description": "Expert code reviewer. Use proactively after code changes.", "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.", "tools": ["Read", "Grep", "Glob", "Bash"], "model": "sonnet" }, "debugger": { "description": "Debugging specialist for errors and test failures.", "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes." } }' ``` For more details on creating and using subagents, see the [subagents documentation](/en/docs/claude-code/sub-agents). For detailed information about print mode (`-p`) including output formats, streaming, verbose logging, and programmatic usage, see the [SDK documentation](/en/docs/claude-code/sdk). ## See also - [Interactive mode](/en/docs/claude-code/interactive-mode) - Shortcuts, input modes, and interactive features - [Slash commands](/en/docs/claude-code/slash-commands) - Interactive session commands - [Quickstart guide](/en/docs/claude-code/quickstart) - Getting started with Claude Code - [Common workflows](/en/docs/claude-code/common-workflows) - Advanced workflows and patterns - [Settings](/en/docs/claude-code/settings) - Configuration options - [SDK documentation](/en/docs/claude-code/sdk) - Programmatic usage and integrations ================================================ FILE: PRPs/ai_docs/optimistic_updates.md ================================================ # Optimistic Updates Pattern Guide ## Core Architecture ### Shared Utilities Module **Location**: `src/features/shared/utils/optimistic.ts` Provides type-safe utilities for managing optimistic state across all features: - `createOptimisticId()` - Generates stable UUIDs using nanoid - `createOptimisticEntity()` - Creates entities with `_optimistic` and `_localId` metadata - `isOptimistic()` - Type guard for checking optimistic state - `replaceOptimisticEntity()` - Replaces optimistic items by `_localId` (race-condition safe) - `removeDuplicateEntities()` - Deduplicates after replacement - `cleanOptimisticMetadata()` - Strips optimistic fields when needed ### TypeScript Interface ```typescript interface OptimisticEntity { _optimistic: boolean; _localId: string; } ``` ## Implementation Patterns ### Mutation Hooks Pattern **Reference**: `src/features/projects/tasks/hooks/useTaskQueries.ts:44-108` 1. **onMutate**: Create optimistic entity with stable ID - Use `createOptimisticEntity()` for type-safe creation - Store `optimisticId` in context for later replacement 2. **onSuccess**: Replace optimistic with server response - Use `replaceOptimisticEntity()` matching by `_localId` - Apply `removeDuplicateEntities()` to prevent duplicates 3. **onError**: Rollback to previous state - Restore snapshot from context ### UI Component Pattern **References**: - `src/features/projects/tasks/components/TaskCard.tsx:39-40,160,186` - `src/features/projects/components/ProjectCard.tsx:32-33,67,93` - `src/features/knowledge/components/KnowledgeCard.tsx:49-50,176,244` 1. Check optimistic state: `const optimistic = isOptimistic(entity)` 2. Apply conditional styling: Add opacity and ring effect when optimistic 3. Display indicator: Use `` component for visual feedback ### Visual Indicator Component **Location**: `src/features/ui/primitives/OptimisticIndicator.tsx` Reusable component showing: - Spinning loader icon (Loader2 from lucide-react) - "Saving..." text with pulse animation - Configurable via props: `showSpinner`, `pulseAnimation` ## Feature Integration ### Tasks - **Mutations**: `src/features/projects/tasks/hooks/useTaskQueries.ts` - **UI**: `src/features/projects/tasks/components/TaskCard.tsx` - Creates tasks with `priority: "medium"` default ### Projects - **Mutations**: `src/features/projects/hooks/useProjectQueries.ts` - **UI**: `src/features/projects/components/ProjectCard.tsx` - Handles `prd: null`, `data_schema: null` for new projects ### Knowledge - **Mutations**: `src/features/knowledge/hooks/useKnowledgeQueries.ts` - **UI**: `src/features/knowledge/components/KnowledgeCard.tsx` - Uses `createOptimisticId()` directly for progress tracking ### Toasts - **Location**: `src/features/shared/hooks/useToast.ts:43` - Uses `createOptimisticId()` for unique toast IDs ## Testing ### Unit Tests **Location**: `src/features/shared/utils/tests/optimistic.test.ts` Covers all utility functions with 8 test cases: - ID uniqueness and format validation - Entity creation with metadata - Type guard functionality - Replacement logic - Deduplication - Metadata cleanup ### Manual Testing Checklist 1. **Rapid Creation**: Create 5+ items quickly - verify no duplicates 2. **Visual Feedback**: Check optimistic indicators appear immediately 3. **ID Stability**: Confirm nanoid-based IDs after server response 4. **Error Handling**: Stop backend, attempt creation - verify rollback 5. **Race Conditions**: Use browser console script for concurrent creates ## Performance Characteristics - **Bundle Impact**: ~130 bytes ([nanoid v5, minified+gzipped](https://bundlephobia.com/package/nanoid@5.0.9)) - build/environment dependent - **Update Speed**: Typically snappy on modern devices; actual latency varies by device and workload - **ID Generation**: Per [nanoid benchmarks](https://github.com/ai/nanoid#benchmark): secure sync ≈5M ops/s, non-secure ≈2.7M ops/s, async crypto ≈135k ops/s - **Memory**: Minimal - only `_optimistic` and `_localId` metadata added per optimistic entity ## Migration Notes ### From Timestamp-based IDs **Before**: `const tempId = \`temp-\${Date.now()}\`` **After**: `const optimisticId = createOptimisticId()` ### Key Differences - No timestamp collisions during rapid creation - Stable IDs survive re-renders - Type-safe with full TypeScript inference - ~60% code reduction through shared utilities ## Best Practices 1. **Always use shared utilities** - Don't implement custom optimistic logic 2. **Match by _localId** - Never match by the entity's `id` field 3. **Include deduplication** - Always call `removeDuplicateEntities()` after replacement 4. **Show visual feedback** - Users should see pending state clearly 5. **Handle errors gracefully** - Always implement rollback in `onError` ## Dependencies - **nanoid**: v5.0.9 - UUID generation - **@tanstack/react-query**: v5.x - Mutation state management - **React**: v18.x - UI components - **TypeScript**: v5.x - Type safety --- *Last updated: Phase 3 implementation (PR #695)* ================================================ FILE: PRPs/templates/prp_base.md ================================================ name: "Base PRP Template v3 - Implementation-Focused with Precision Standards" description: | --- ## Goal **Feature Goal**: [Specific, measurable end state of what needs to be built] **Deliverable**: [Concrete artifact - API endpoint, service class, integration, etc.] **Success Definition**: [How you'll know this is complete and working] ## User Persona (if applicable) **Target User**: [Specific user type - developer, end user, admin, etc.] **Use Case**: [Primary scenario when this feature will be used] **User Journey**: [Step-by-step flow of how user interacts with this feature] **Pain Points Addressed**: [Specific user frustrations this feature solves] ## Why - [Business value and user impact] - [Integration with existing features] - [Problems this solves and for whom] ## What [User-visible behavior and technical requirements] ### Success Criteria - [ ] [Specific measurable outcomes] ## All Needed Context ### Context Completeness Check _Before writing this PRP, validate: "If someone knew nothing about this codebase, would they have everything needed to implement this successfully?"_ ### Documentation & References ```yaml # MUST READ - Include these in your context window - url: [Complete URL with section anchor] why: [Specific methods/concepts needed for implementation] critical: [Key insights that prevent common implementation errors] - file: [exact/path/to/pattern/file.py] why: [Specific pattern to follow - class structure, error handling, etc.] pattern: [Brief description of what pattern to extract] gotcha: [Known constraints or limitations to avoid] - docfile: [PRPs/ai_docs/domain_specific.md] why: [Custom documentation for complex library/integration patterns] section: [Specific section if document is large] ``` ### Current Codebase tree (run `tree` in the root of the project) to get an overview of the codebase ```bash ``` ### Desired Codebase tree with files to be added and responsibility of file ```bash ``` ### Known Gotchas of our codebase & Library Quirks ```python # CRITICAL: [Library name] requires [specific setup] # Example: FastAPI requires async functions for endpoints # Example: This ORM doesn't support batch inserts over 1000 records ``` ## Implementation Blueprint ### Data models and structure Create the core data models, we ensure type safety and consistency. ```python Examples: - orm models - pydantic models - pydantic schemas - pydantic validators ``` ### Implementation Tasks (ordered by dependencies) ```yaml Task 1: CREATE src/models/{domain}_models.py - IMPLEMENT: {SpecificModel}Request, {SpecificModel}Response Pydantic models - FOLLOW pattern: src/models/existing_model.py (field validation approach) - NAMING: CamelCase for classes, snake_case for fields - PLACEMENT: Domain-specific model file in src/models/ Task 2: CREATE src/services/{domain}_service.py - IMPLEMENT: {Domain}Service class with async methods - FOLLOW pattern: src/services/database_service.py (service structure, error handling) - NAMING: {Domain}Service class, async def create_*, get_*, update_*, delete_* methods - DEPENDENCIES: Import models from Task 1 - PLACEMENT: Service layer in src/services/ Task 3: CREATE src/tools/{action}_{resource}.py - IMPLEMENT: MCP tool wrapper calling service methods - FOLLOW pattern: src/tools/existing_tool.py (FastMCP tool structure) - NAMING: snake_case file name, descriptive tool function name - DEPENDENCIES: Import service from Task 2 - PLACEMENT: Tool layer in src/tools/ Task 4: MODIFY src/main.py or src/server.py - INTEGRATE: Register new tool with MCP server - FIND pattern: existing tool registrations - ADD: Import and register new tool following existing pattern - PRESERVE: Existing tool registrations and server configuration Task 5: CREATE src/services/tests/test_{domain}_service.py - IMPLEMENT: Unit tests for all service methods (happy path, edge cases, error handling) - FOLLOW pattern: src/services/tests/test_existing_service.py (fixture usage, assertion patterns) - NAMING: test_{method}_{scenario} function naming - COVERAGE: All public methods with positive and negative test cases - PLACEMENT: Tests alongside the code they test Task 6: CREATE src/tools/tests/test_{action}_{resource}.py - IMPLEMENT: Unit tests for MCP tool functionality - FOLLOW pattern: src/tools/tests/test_existing_tool.py (MCP tool testing approach) - MOCK: External service dependencies - COVERAGE: Tool input validation, success responses, error handling - PLACEMENT: Tool tests in src/tools/tests/ ``` ### Implementation Patterns & Key Details ```python # Show critical patterns and gotchas - keep concise, focus on non-obvious details # Example: Service method pattern async def {domain}_operation(self, request: {Domain}Request) -> {Domain}Response: # PATTERN: Input validation first (follow src/services/existing_service.py) validated = self.validate_request(request) # GOTCHA: [Library-specific constraint or requirement] # PATTERN: Error handling approach (reference existing service pattern) # CRITICAL: [Non-obvious requirement or configuration detail] return {Domain}Response(status="success", data=result) # Example: MCP tool pattern @app.tool() async def {tool_name}({parameters}) -> str: # PATTERN: Tool validation and service delegation (see src/tools/existing_tool.py) # RETURN: JSON string with standardized response format ``` ### Integration Points ```yaml DATABASE: - migration: "Add column 'feature_enabled' to users table" - index: "CREATE INDEX idx_feature_lookup ON users(feature_id)" CONFIG: - add to: config/settings.py - pattern: "FEATURE_TIMEOUT = int(os.getenv('FEATURE_TIMEOUT', '30'))" ROUTES: - add to: src/api/routes.py - pattern: "router.include_router(feature_router, prefix='/feature')" ``` ## Validation Loop ### Level 1: Syntax & Style (Immediate Feedback) ```bash # Run after each file creation - fix before proceeding ruff check src/{new_files} --fix # Auto-format and fix linting issues mypy src/{new_files} # Type checking with specific files ruff format src/{new_files} # Ensure consistent formatting # Project-wide validation ruff check src/ --fix mypy src/ ruff format src/ # Expected: Zero errors. If errors exist, READ output and fix before proceeding. ``` ### Level 2: Unit Tests (Component Validation) ```bash # Test each component as it's created uv run pytest src/services/tests/test_{domain}_service.py -v uv run pytest src/tools/tests/test_{action}_{resource}.py -v # Full test suite for affected areas uv run pytest src/services/tests/ -v uv run pytest src/tools/tests/ -v # Coverage validation (if coverage tools available) uv run pytest src/ --cov=src --cov-report=term-missing # Expected: All tests pass. If failing, debug root cause and fix implementation. ``` ### Level 3: Integration Testing (System Validation) ```bash # Service startup validation uv run python main.py & sleep 3 # Allow startup time # Health check validation curl -f http://localhost:8000/health || echo "Service health check failed" # Feature-specific endpoint testing curl -X POST http://localhost:8000/{your_endpoint} \ -H "Content-Type: application/json" \ -d '{"test": "data"}' \ | jq . # Pretty print JSON response # MCP server validation (if MCP-based) # Test MCP tool functionality echo '{"method": "tools/call", "params": {"name": "{tool_name}", "arguments": {}}}' | \ uv run python -m src.main # Database validation (if database integration) # Verify database schema, connections, migrations psql $DATABASE_URL -c "SELECT 1;" || echo "Database connection failed" # Expected: All integrations working, proper responses, no connection errors ``` ### Level 4: Creative & Domain-Specific Validation ```bash # MCP Server Validation Examples: # Playwright MCP (for web interfaces) playwright-mcp --url http://localhost:8000 --test-user-journey # Docker MCP (for containerized services) docker-mcp --build --test --cleanup # Database MCP (for data operations) database-mcp --validate-schema --test-queries --check-performance # Custom Business Logic Validation # [Add domain-specific validation commands here] # Performance Testing (if performance requirements) ab -n 100 -c 10 http://localhost:8000/{endpoint} # Security Scanning (if security requirements) bandit -r src/ # Load Testing (if scalability requirements) # wrk -t12 -c400 -d30s http://localhost:8000/{endpoint} # API Documentation Validation (if API endpoints) # swagger-codegen validate -i openapi.json # Expected: All creative validations pass, performance meets requirements ``` ## Final Validation Checklist ### Technical Validation - [ ] All 4 validation levels completed successfully - [ ] All tests pass: `uv run pytest src/ -v` - [ ] No linting errors: `uv run ruff check src/` - [ ] No type errors: `uv run mypy src/` - [ ] No formatting issues: `uv run ruff format src/ --check` ### Feature Validation - [ ] All success criteria from "What" section met - [ ] Manual testing successful: [specific commands from Level 3] - [ ] Error cases handled gracefully with proper error messages - [ ] Integration points work as specified - [ ] User persona requirements satisfied (if applicable) ### Code Quality Validation - [ ] Follows existing codebase patterns and naming conventions - [ ] File placement matches desired codebase tree structure - [ ] Anti-patterns avoided (check against Anti-Patterns section) - [ ] Dependencies properly managed and imported - [ ] Configuration changes properly integrated ### Documentation & Deployment - [ ] Code is self-documenting with clear variable/function names - [ ] Logs are informative but not verbose - [ ] Environment variables documented if new ones added --- ## Anti-Patterns to Avoid - ❌ Don't create new patterns when existing ones work - ❌ Don't skip validation because "it should work" - ❌ Don't ignore failing tests - fix them - ❌ Don't use sync functions in async context - ❌ Don't hardcode values that should be config - ❌ Don't catch all exceptions - be specific ================================================ FILE: PRPs/templates/prp_story_task.md ================================================ --- name: "Story PRP Template - Task Implementation Focus" description: "Template for converting user stories into executable implementation tasks" --- ## Original Story Paste in the original story shared by the user below: ``` [User story/task description from Jira/Linear/etc] ``` ## Story Metadata **Story Type**: [Feature/Bug/Enhancement/Refactor] **Estimated Complexity**: [Low/Medium/High] **Primary Systems Affected**: [List of main components/services] --- ## CONTEXT REFERENCES [Auto-discovered documentation and patterns] - {file_path} - {Why this pattern/file is relevant} - {doc_path} - {Specific sections needed for implementation} - {external_url} - {Library documentation or examples} --- ## IMPLEMENTATION TASKS [Task blocks in dependency order - each block is atomic and testable] ### Guidelines for Tasks - We are using Information dense keywords to be specific and concise about implementation steps and details. - The tasks have to be detailed and specific to ensure clarity and accuracy. - The developer who will execute the tasks should be able to complete the task using only the context of this file, with references to relevant codebase paths and integration points. ### {ACTION} {target_file}: - {VERB/KEYWORD}: {Specific implementation detail} - {PATTERN}: {Existing pattern to follow from codebase} - {IMPORTS}: {Required imports or dependencies} - {GOTCHA}: {Known issues or constraints to avoid} - **VALIDATE**: `{executable validation command}` ### Example Format: ### CREATE services/user_service.py: - IMPLEMENT: UserService class with async CRUD operations - PATTERN: Follow services/product_service.py structure - IMPORTS: from models.user import User; from db import get_session - GOTCHA: Always use async session context manager - **VALIDATE**: ` uv run python -c "from services.user_service import UserService; print('✓ Import successful')"` ### UPDATE api/routes.py: - ADD: user_router to main router - FIND: `app.include_router(product_router)` - INSERT: `app.include_router(user_router, prefix="/users", tags=["users"])` - **VALIDATE**: `grep -q "user_router" api/routes.py && echo "✓ Router added"` ### ADD tests/ - CREATE: tests/user_service_test.py - IMPLEMENT: Test cases for UserService class - PATTERN: Follow tests/product_service_test.py structure - IMPORTS: from services.user_service import UserService; from models.user import User; from db import get_session - GOTCHA: Use async session context manager in tests - **VALIDATE**: `uv run python -m pytest tests/user_service_test.py && echo "✓ Tests passed"` --- ## Validation Loop ### Level 1: Syntax & Style (Immediate Feedback) ```bash # Run after each file creation - fix before proceeding ruff check src/{new_files} --fix # Auto-format and fix linting issues mypy src/{new_files} # Type checking with specific files ruff format src/{new_files} # Ensure consistent formatting # Project-wide validation ruff check src/ --fix mypy src/ ruff format src/ # Expected: Zero errors. If errors exist, READ output and fix before proceeding. ``` ### Level 2: Unit Tests (Component Validation) ```bash # Test each component as it's created uv run pytest src/services/tests/test_{domain}_service.py -v uv run pytest src/tools/tests/test_{action}_{resource}.py -v # Full test suite for affected areas uv run pytest src/services/tests/ -v uv run pytest src/tools/tests/ -v # Coverage validation (if coverage tools available) uv run pytest src/ --cov=src --cov-report=term-missing # Expected: All tests pass. If failing, debug root cause and fix implementation. ``` ### Level 3: Integration Testing (System Validation) ```bash # Service startup validation uv run python main.py & sleep 3 # Allow startup time # Health check validation curl -f http://localhost:8000/health || echo "Service health check failed" # Feature-specific endpoint testing curl -X POST http://localhost:8000/{your_endpoint} \ -H "Content-Type: application/json" \ -d '{"test": "data"}' \ | jq . # Pretty print JSON response # MCP server validation (if MCP-based) # Test MCP tool functionality echo '{"method": "tools/call", "params": {"name": "{tool_name}", "arguments": {}}}' | \ uv run python -m src.main # Database validation (if database integration) # Verify database schema, connections, migrations psql $DATABASE_URL -c "SELECT 1;" || echo "Database connection failed" # Expected: All integrations working, proper responses, no connection errors ``` ### Level 4: Creative & Domain-Specific Validation You can use CLI that are installed on the system or MCP servers to extend the validation and self closing loop. Identify if you are connected to any MCP servers that can be used for validation and if you have any cli tools installed on the system that can help with validation. For example: ```bash # MCP Server Validation Examples: # Playwright MCP (for web interfaces) playwright-mcp --url http://localhost:8000 --test-user-journey # Docker MCP (for containerized services) docker-mcp --build --test --cleanup # Database MCP (for data operations) database-mcp --validate-schema --test-queries --check-performance ``` --- ## COMPLETION CHECKLIST - [ ] All tasks completed - [ ] Each task validation passed - [ ] Full test suite passes - [ ] No linting errors - [ ] All available validation gates passed - [ ] Story acceptance criteria met --- ## Notes [Any additional context, decisions made, or follow-up items] ================================================ FILE: README.md ================================================

Archon Main Graphic

coleam00%2FArchon | Trendshift

Power up your AI coding assistants with your own custom knowledge base and task management as an MCP server

Quick Start • Upgrading • What's Included • Architecture • Troubleshooting

--- ## 🎯 What is Archon? > Archon is currently in beta! Expect things to not work 100%, and please feel free to share any feedback and contribute with fixes/new features! Thank you to everyone for all the excitement we have for Archon already, as well as the bug reports, PRs, and discussions. It's a lot for our small team to get through but we're committed to addressing everything and making Archon into the best tool it possibly can be! Archon is the **command center** for AI coding assistants. For you, it's a sleek interface to manage knowledge, context, and tasks for your projects. For the AI coding assistant(s), it's a **Model Context Protocol (MCP) server** to collaborate on and leverage the same knowledge, context, and tasks. Connect Claude Code, Kiro, Cursor, Windsurf, etc. to give your AI agents access to: - **Your documentation** (crawled websites, uploaded PDFs/docs) - **Smart search capabilities** with advanced RAG strategies - **Task management** integrated with your knowledge base - **Real-time updates** as you add new content and collaborate with your coding assistant on tasks - **Much more** coming soon to build Archon into an integrated environment for all context engineering This new vision for Archon replaces the old one (the agenteer). Archon used to be the AI agent that builds other agents, and now you can use Archon to do that and more. > It doesn't matter what you're building or if it's a new/existing codebase - Archon's knowledge and task management capabilities will improve the output of **any** AI driven coding. ## 🔗 Important Links - **[GitHub Discussions](https://github.com/coleam00/Archon/discussions)** - Join the conversation and share ideas about Archon - **[Contributing Guide](CONTRIBUTING.md)** - How to get involved and contribute to Archon - **[Introduction Video](https://youtu.be/8pRc_s2VQIo)** - Getting started guide and vision for Archon - **[Archon Kanban Board](https://github.com/users/coleam00/projects/1)** - Where maintainers are managing issues/features - **[Dynamous AI Mastery](https://dynamous.ai)** - The birthplace of Archon - come join a vibrant community of other early AI adopters all helping each other transform their careers and businesses! ## Quick Start

Archon Setup Tutorial
📺 Click to watch the setup tutorial on YouTube
-> Example AI coding workflow in the video <-

### Prerequisites - [Docker Desktop](https://www.docker.com/products/docker-desktop/) - [Node.js 18+](https://nodejs.org/) (for hybrid development mode) - [Supabase](https://supabase.com/) account (free tier or local Supabase both work) - [OpenAI API key](https://platform.openai.com/api-keys) (Gemini and Ollama are supported too!) - (OPTIONAL) [Make](https://www.gnu.org/software/make/) (see [Installing Make](#installing-make) below) ### Setup Instructions 1. **Clone Repository**: ```bash git clone -b stable https://github.com/coleam00/archon.git ``` ```bash cd archon ``` **Note:** The `stable` branch is recommended for using Archon. If you want to contribute or try the latest features, use the `main` branch with `git clone https://github.com/coleam00/archon.git` 2. **Environment Configuration**: ```bash cp .env.example .env # Edit .env and add your Supabase credentials: # SUPABASE_URL=https://your-project.supabase.co # SUPABASE_SERVICE_KEY=your-service-key-here ``` IMPORTANT NOTES: - For cloud Supabase: They recently introduced a new type of service role key but use the legacy one (the longer one). - For local Supabase: Set `SUPABASE_URL` to http://host.docker.internal:8000 (unless you have an IP address set up). To get `SUPABASE_SERVICE_KEY` run `supabase status -o env`. 3. **Database Setup**: In your [Supabase project](https://supabase.com/dashboard) SQL Editor, copy, paste, and execute the contents of `migration/complete_setup.sql` 4. **Start Services** (choose one): **Full Docker Mode (Recommended for Normal Archon Usage)** ```bash docker compose up --build -d ``` This starts all core microservices in Docker: - **Server**: Core API and business logic (Port: 8181) - **MCP Server**: Protocol interface for AI clients (Port: 8051) - **UI**: Web interface (Port: 3737) Ports are configurable in your .env as well! 5. **Configure API Keys**: - Open http://localhost:3737 - You'll automatically be brought through an onboarding flow to set your API key (OpenAI is default) ## ⚡ Quick Test Once everything is running: 1. **Test Web Crawling**: Go to http://localhost:3737 → Knowledge Base → "Crawl Website" → Enter a doc URL (such as https://ai.pydantic.dev/llms.txt) 2. **Test Document Upload**: Knowledge Base → Upload a PDF 3. **Test Projects**: Projects → Create a new project and add tasks 4. **Integrate with your AI coding assistant**: MCP Dashboard → Copy connection config for your AI coding assistant ## Installing Make
🛠️ Make installation (OPTIONAL - For Dev Workflows) ### Windows ```bash # Option 1: Using Chocolatey choco install make # Option 2: Using Scoop scoop install make # Option 3: Using WSL2 wsl --install # Then in WSL: sudo apt-get install make ``` ### macOS ```bash # Make comes pre-installed on macOS # If needed: brew install make ``` ### Linux ```bash # Debian/Ubuntu sudo apt-get install make # RHEL/CentOS/Fedora sudo yum install make ```
🚀 Quick Command Reference for Make
| Command | Description | | ----------------- | ------------------------------------------------------- | | `make dev` | Start hybrid dev (backend in Docker, frontend local) ⭐ | | `make dev-docker` | Everything in Docker | | `make stop` | Stop all services | | `make test` | Run all tests | | `make lint` | Run linters | | `make install` | Install dependencies | | `make check` | Check environment setup | | `make clean` | Remove containers and volumes (with confirmation) |
## 🔄 Database Reset (Start Fresh if Needed) If you need to completely reset your database and start fresh:
⚠️ Reset Database - This will delete ALL data for Archon! 1. **Run Reset Script**: In your Supabase SQL Editor, run the contents of `migration/RESET_DB.sql` ⚠️ WARNING: This will delete all Archon specific tables and data! Nothing else will be touched in your DB though. 2. **Rebuild Database**: After reset, run `migration/complete_setup.sql` to create all the tables again. 3. **Restart Services**: ```bash docker compose --profile full up -d ``` 4. **Reconfigure**: - Select your LLM/embedding provider and set the API key again - Re-upload any documents or re-crawl websites The reset script safely removes all tables, functions, triggers, and policies with proper dependency handling.
## 📚 Documentation ### Core Services | Service | Container Name | Default URL | Purpose | | -------------------------- | -------------------------- | --------------------- | ------------------------------------------ | | **Web Interface** | archon-ui | http://localhost:3737 | Main dashboard and controls | | **API Service** | archon-server | http://localhost:8181 | Web crawling, document processing | | **MCP Server** | archon-mcp | http://localhost:8051 | Model Context Protocol interface | | **Agents Service** | archon-agents | http://localhost:8052 | AI/ML operations, reranking | | **Agent Work Orders** *(optional)* | archon-agent-work-orders | http://localhost:8053 | Workflow execution with Claude Code CLI | ## Upgrading To upgrade Archon to the latest version: 1. **Pull latest changes**: ```bash git pull ``` 2. **Rebuild and restart containers**: ```bash docker compose up -d --build ``` This rebuilds containers with the latest code and restarts all services. 3. **Check for database migrations**: - Open the Archon settings in your browser: [http://localhost:3737/settings](http://localhost:3737/settings) - Navigate to the **Database Migrations** section - If there are pending migrations, the UI will display them with clear instructions - Click on each migration to view and copy the SQL - Run the SQL scripts in your Supabase SQL editor in the order shown ## What's Included ### 🧠 Knowledge Management - **Smart Web Crawling**: Automatically detects and crawls entire documentation sites, sitemaps, and individual pages - **Document Processing**: Upload and process PDFs, Word docs, markdown files, and text documents with intelligent chunking - **Code Example Extraction**: Automatically identifies and indexes code examples from documentation for enhanced search - **Vector Search**: Advanced semantic search with contextual embeddings for precise knowledge retrieval - **Source Management**: Organize knowledge by source, type, and tags for easy filtering ### 🤖 AI Integration - **Model Context Protocol (MCP)**: Connect any MCP-compatible client (Claude Code, Cursor, even non-AI coding assistants like Claude Desktop) - **MCP Tools**: Comprehensive yet simple set of tools for RAG queries, task management, and project operations - **Multi-LLM Support**: Works with OpenAI, Ollama, and Google Gemini models - **RAG Strategies**: Hybrid search, contextual embeddings, and result reranking for optimal AI responses - **Real-time Streaming**: Live responses from AI agents with progress tracking ### 📋 Project & Task Management - **Hierarchical Projects**: Organize work with projects, features, and tasks in a structured workflow - **AI-Assisted Creation**: Generate project requirements and tasks using integrated AI agents - **Document Management**: Version-controlled documents with collaborative editing capabilities - **Progress Tracking**: Real-time updates and status management across all project activities ### 🔄 Real-time Collaboration - **WebSocket Updates**: Live progress tracking for crawling, processing, and AI operations - **Multi-user Support**: Collaborative knowledge building and project management - **Background Processing**: Asynchronous operations that don't block the user interface - **Health Monitoring**: Built-in service health checks and automatic reconnection ## Architecture ### Microservices Structure Archon uses true microservices architecture with clear separation of concerns: ``` ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ Frontend UI │ │ Server (API) │ │ MCP Server │ │ Agents Service │ │ │ │ │ │ │ │ │ │ React + Vite │◄──►│ FastAPI + │◄──►│ Lightweight │◄──►│ PydanticAI │ │ Port 3737 │ │ SocketIO │ │ HTTP Wrapper │ │ Port 8052 │ │ │ │ Port 8181 │ │ Port 8051 │ │ │ └─────────────────┘ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ │ │ │ └────────────────────────┼────────────────────────┼────────────────────────┘ │ │ ┌─────────────────┐ │ │ Database │ │ │ │ │ │ Supabase │◄──────────────┘ │ PostgreSQL │ │ PGVector │ └─────────────────┘ ``` ### Service Responsibilities | Service | Location | Purpose | Key Features | | ------------------------ | ------------------------------ | -------------------------------- | ------------------------------------------------------------------ | | **Frontend** | `archon-ui-main/` | Web interface and dashboard | React, TypeScript, TailwindCSS, Socket.IO client | | **Server** | `python/src/server/` | Core business logic and APIs | FastAPI, service layer, Socket.IO broadcasts, all ML/AI operations | | **MCP Server** | `python/src/mcp/` | MCP protocol interface | Lightweight HTTP wrapper, MCP tools, session management | | **Agents** | `python/src/agents/` | PydanticAI agent hosting | Document and RAG agents, streaming responses | | **Agent Work Orders** *(optional)* | `python/src/agent_work_orders/` | Workflow execution engine | Claude Code CLI automation, repository management, SSE updates | ### Communication Patterns - **HTTP-based**: All inter-service communication uses HTTP APIs - **Socket.IO**: Real-time updates from Server to Frontend - **MCP Protocol**: AI clients connect to MCP Server via SSE or stdio - **No Direct Imports**: Services are truly independent with no shared code dependencies ### Key Architectural Benefits - **Lightweight Containers**: Each service contains only required dependencies - **Independent Scaling**: Services can be scaled independently based on load - **Development Flexibility**: Teams can work on different services without conflicts - **Technology Diversity**: Each service uses the best tools for its specific purpose ## 🔧 Configuring Custom Ports & Hostname By default, Archon services run on the following ports: - **archon-ui**: 3737 - **archon-server**: 8181 - **archon-mcp**: 8051 - **archon-agents**: 8052 (optional) - **archon-agent-work-orders**: 8053 (optional) ### Changing Ports To use custom ports, add these variables to your `.env` file: ```bash # Service Ports Configuration ARCHON_UI_PORT=3737 ARCHON_SERVER_PORT=8181 ARCHON_MCP_PORT=8051 ARCHON_AGENTS_PORT=8052 AGENT_WORK_ORDERS_PORT=8053 ``` Example: Running on different ports: ```bash ARCHON_SERVER_PORT=8282 ARCHON_MCP_PORT=8151 ``` ### Configuring Hostname By default, Archon uses `localhost` as the hostname. You can configure a custom hostname or IP address by setting the `HOST` variable in your `.env` file: ```bash # Hostname Configuration HOST=localhost # Default # Examples of custom hostnames: HOST=192.168.1.100 # Use specific IP address HOST=archon.local # Use custom domain HOST=myserver.com # Use public domain ``` This is useful when: - Running Archon on a different machine and accessing it remotely - Using a custom domain name for your installation - Deploying in a network environment where `localhost` isn't accessible After changing hostname or ports: 1. Restart Docker containers: `docker compose down && docker compose --profile full up -d` 2. Access the UI at: `http://${HOST}:${ARCHON_UI_PORT}` 3. Update your AI client configuration with the new hostname and MCP port ## 🔧 Development ### Quick Start ```bash # Install dependencies make install # Start development (recommended) make dev # Backend in Docker, frontend local with hot reload # Alternative: Everything in Docker make dev-docker # All services in Docker # Stop everything (local FE needs to be stopped manually) make stop ``` ### Development Modes #### Hybrid Mode (Recommended) - `make dev` Best for active development with instant frontend updates: - Backend services run in Docker (isolated, consistent) - Frontend runs locally with hot module replacement - Instant UI updates without Docker rebuilds #### Full Docker Mode - `make dev-docker` For all services in Docker environment: - All services run in Docker containers - Better for integration testing - Slower frontend updates ### Testing & Code Quality ```bash # Run tests make test # Run all tests make test-fe # Run frontend tests make test-be # Run backend tests # Run linters make lint # Lint all code make lint-fe # Lint frontend code make lint-be # Lint backend code # Check environment make check # Verify environment setup # Clean up make clean # Remove containers and volumes (asks for confirmation) ``` ### Viewing Logs ```bash # View logs using Docker Compose directly docker compose logs -f # All services docker compose logs -f archon-server # API server docker compose logs -f archon-mcp # MCP server docker compose logs -f archon-ui # Frontend ``` **Note**: The backend services are configured with `--reload` flag in their uvicorn commands and have source code mounted as volumes for automatic hot reloading when you make changes. ## Troubleshooting ### Common Issues and Solutions #### Port Conflicts If you see "Port already in use" errors: ```bash # Check what's using a port (e.g., 3737) lsof -i :3737 # Stop all containers and local services make stop # Change the port in .env ``` #### Docker Permission Issues (Linux) If you encounter permission errors with Docker: ```bash # Add your user to the docker group sudo usermod -aG docker $USER # Log out and back in, or run newgrp docker ``` #### Windows-Specific Issues - **Make not found**: Install Make via Chocolatey, Scoop, or WSL2 (see [Installing Make](#installing-make)) - **Line ending issues**: Configure Git to use LF endings: ```bash git config --global core.autocrlf false ``` #### Frontend Can't Connect to Backend - Check backend is running: `curl http://localhost:8181/health` - Verify port configuration in `.env` - For custom ports, ensure both `ARCHON_SERVER_PORT` and `VITE_ARCHON_SERVER_PORT` are set #### Docker Compose Hangs If `docker compose` commands hang: ```bash # Reset Docker Compose docker compose down --remove-orphans docker system prune -f # Restart Docker Desktop (if applicable) ``` #### Hot Reload Not Working - **Frontend**: Ensure you're running in hybrid mode (`make dev`) for best HMR experience - **Backend**: Check that volumes are mounted correctly in `docker-compose.yml` - **File permissions**: On some systems, mounted volumes may have permission issues ## 📈 Progress

Star History Chart

## 📄 License Archon Community License (ACL) v1.2 - see [LICENSE](LICENSE) file for details. **TL;DR**: Archon is free, open, and hackable. Run it, fork it, share it - just don't sell it as-a-service without permission. ================================================ FILE: archon-example-workflow/.claude/agents/codebase-analyst.md ================================================ --- name: "codebase-analyst" description: "Use proactively to find codebase patterns, coding style and team standards. Specialized agent for deep codebase pattern analysis and convention discovery" model: "sonnet" --- You are a specialized codebase analysis agent focused on discovering patterns, conventions, and implementation approaches. ## Your Mission Perform deep, systematic analysis of codebases to extract: - Architectural patterns and project structure - Coding conventions and naming standards - Integration patterns between components - Testing approaches and validation commands - External library usage and configuration ## Analysis Methodology ### 1. Project Structure Discovery - Start looking for Architecture docs rules files such as claude.md, agents.md, cursorrules, windsurfrules, agent wiki, or similar documentation - Continue with root-level config files (package.json, pyproject.toml, go.mod, etc.) - Map directory structure to understand organization - Identify primary language and framework - Note build/run commands ### 2. Pattern Extraction - Find similar implementations to the requested feature - Extract common patterns (error handling, API structure, data flow) - Identify naming conventions (files, functions, variables) - Document import patterns and module organization ### 3. Integration Analysis - How are new features typically added? - Where do routes/endpoints get registered? - How are services/components wired together? - What's the typical file creation pattern? ### 4. Testing Patterns - What test framework is used? - How are tests structured? - What are common test patterns? - Extract validation command examples ### 5. Documentation Discovery - Check for README files - Find API documentation - Look for inline code comments with patterns - Check PRPs/ai_docs/ for curated documentation ## Output Format Provide findings in structured format: ```yaml project: language: [detected language] framework: [main framework] structure: [brief description] patterns: naming: files: [pattern description] functions: [pattern description] classes: [pattern description] architecture: services: [how services are structured] models: [data model patterns] api: [API patterns] testing: framework: [test framework] structure: [test file organization] commands: [common test commands] similar_implementations: - file: [path] relevance: [why relevant] pattern: [what to learn from it] libraries: - name: [library] usage: [how it's used] patterns: [integration patterns] validation_commands: syntax: [linting/formatting commands] test: [test commands] run: [run/serve commands] ``` ## Key Principles - Be specific - point to exact files and line numbers - Extract executable commands, not abstract descriptions - Focus on patterns that repeat across the codebase - Note both good patterns to follow and anti-patterns to avoid - Prioritize relevance to the requested feature/story ## Search Strategy 1. Start broad (project structure) then narrow (specific patterns) 2. Use parallel searches when investigating multiple aspects 3. Follow references - if a file imports something, investigate it 4. Look for "similar" not "same" - patterns often repeat with variations Remember: Your analysis directly determines implementation success. Be thorough, specific, and actionable. ================================================ FILE: archon-example-workflow/.claude/agents/validator.md ================================================ --- name: validator description: Testing specialist for software features. USE AUTOMATICALLY after implementation to create simple unit tests, validate functionality, and ensure readiness. IMPORTANT - You must pass exactly what was built as part of the prompt so the validator knows what features to test. tools: Read, Write, Grep, Glob, Bash, TodoWrite color: green --- # Software Feature Validator You are an expert QA engineer specializing in creating simple, effective unit tests for newly implemented software features. Your role is to ensure the implemented functionality works correctly through straightforward testing. ## Primary Objective Create simple, focused unit tests that validate the core functionality of what was just built. Keep tests minimal but effective - focus on the happy path and critical edge cases only. ## Core Responsibilities ### 1. Understand What Was Built First, understand exactly what feature or functionality was implemented by: - Reading the relevant code files - Identifying the main functions/components created - Understanding the expected inputs and outputs - Noting any external dependencies or integrations ### 2. Create Simple Unit Tests Write straightforward tests that: - **Test the happy path**: Verify the feature works with normal, expected inputs - **Test critical edge cases**: Empty inputs, null values, boundary conditions - **Test error handling**: Ensure errors are handled gracefully - **Keep it simple**: 3-5 tests per feature is often sufficient ### 3. Test Structure Guidelines #### For JavaScript/TypeScript Projects ```javascript // Simple test example describe('FeatureName', () => { test('should handle normal input correctly', () => { const result = myFunction('normal input'); expect(result).toBe('expected output'); }); test('should handle empty input', () => { const result = myFunction(''); expect(result).toBe(null); }); test('should throw error for invalid input', () => { expect(() => myFunction(null)).toThrow(); }); }); ``` #### For Python Projects ```python # Simple test example import unittest from my_module import my_function class TestFeature(unittest.TestCase): def test_normal_input(self): result = my_function("normal input") self.assertEqual(result, "expected output") def test_empty_input(self): result = my_function("") self.assertIsNone(result) def test_invalid_input(self): with self.assertRaises(ValueError): my_function(None) ``` ### 4. Test Execution Process 1. **Identify test framework**: Check package.json, requirements.txt, or project config 2. **Create test file**: Place in appropriate test directory (tests/, __tests__, spec/) 3. **Write simple tests**: Focus on functionality, not coverage percentages 4. **Run tests**: Use the project's test command (npm test, pytest, etc.) 5. **Fix any issues**: If tests fail, determine if it's a test issue or code issue ## Validation Approach ### Keep It Simple - Don't over-engineer tests - Focus on "does it work?" not "is every line covered?" - 3-5 good tests are better than 20 redundant ones - Test behavior, not implementation details ### What to Test ✅ Main functionality works as expected ✅ Common edge cases are handled ✅ Errors don't crash the application ✅ API contracts are honored (if applicable) ✅ Data transformations are correct ### What NOT to Test ❌ Every possible combination of inputs ❌ Internal implementation details ❌ Third-party library functionality ❌ Trivial getters/setters ❌ Configuration values ## Common Test Patterns ### API Endpoint Test ```javascript test('API returns correct data', async () => { const response = await fetch('/api/endpoint'); const data = await response.json(); expect(response.status).toBe(200); expect(data).toHaveProperty('expectedField'); }); ``` ### Data Processing Test ```python def test_data_transformation(): input_data = {"key": "value"} result = transform_data(input_data) assert result["key"] == "TRANSFORMED_VALUE" ``` ### UI Component Test ```javascript test('Button triggers action', () => { const onClick = jest.fn(); render(); fireEvent.click(screen.getByText('Click me')); expect(onClick).toHaveBeenCalled(); }); ``` ## Final Validation Checklist Before completing validation: - [ ] Tests are simple and readable - [ ] Main functionality is tested - [ ] Critical edge cases are covered - [ ] Tests actually run and pass - [ ] No overly complex test setups - [ ] Test names clearly describe what they test ## Output Format After creating and running tests, provide: ```markdown # Validation Complete ## Tests Created - [Test file name]: [Number] tests - Total tests: [X] - All passing: [Yes/No] ## What Was Tested - ✅ [Feature 1]: Working correctly - ✅ [Feature 2]: Handles edge cases - ⚠️ [Feature 3]: [Any issues found] ## Test Commands Run tests with: `[command used]` ## Notes [Any important observations or recommendations] ``` ## Remember - Simple tests are better than complex ones - Focus on functionality, not coverage metrics - Test what matters, skip what doesn't - Clear test names help future debugging - Working software is the goal, tests are the safety net ================================================ FILE: archon-example-workflow/.claude/commands/create-plan.md ================================================ --- description: Create a comprehensive implementation plan from requirements document through extensive research argument-hint: [requirements-file-path] --- # Create Implementation Plan from Requirements You are about to create a comprehensive implementation plan based on initial requirements. This involves extensive research, analysis, and planning to produce a detailed roadmap for execution. ## Step 1: Read and Analyze Requirements Read the requirements document from: $ARGUMENTS Extract and understand: - Core feature requests and objectives - Technical requirements and constraints - Expected outcomes and success criteria - Integration points with existing systems - Performance and scalability requirements - Any specific technologies or frameworks mentioned ## Step 2: Research Phase ### 2.1 Knowledge Base Search (if instructed) If Archon RAG is available and relevant: - Use `mcp__archon__rag_get_available_sources()` to see available documentation - Search for relevant patterns: `mcp__archon__rag_search_knowledge_base(query="...")` - Find code examples: `mcp__archon__rag_search_code_examples(query="...")` - Focus on implementation patterns, best practices, and similar features ### 2.2 Codebase Analysis (for existing projects) If this is for an existing codebase: **IMPORTANT: Use the `codebase-analyst` agent for deep pattern analysis** - Launch the codebase-analyst agent using the Task tool to perform comprehensive pattern discovery - The agent will analyze: architecture patterns, coding conventions, testing approaches, and similar implementations - Use the agent's findings to ensure your plan follows existing patterns and conventions For quick searches you can also: - Use Grep to find specific features or patterns - Identify the project structure and conventions - Locate relevant modules and components - Understand existing architecture and design patterns - Find integration points for new features - Check for existing utilities or helpers to reuse ## Step 3: Planning and Design Based on your research, create a detailed plan that includes: ### 3.1 Task Breakdown Create a prioritized list of implementation tasks: - Each task should be specific and actionable - Tasks should be sized appropriately - Include dependencies between tasks - Order tasks logically for implementation flow ### 3.2 Technical Architecture Define the technical approach: - Component structure and organization - Data flow and state management - API design (if applicable) - Database schema changes (if needed) - Integration points with existing code ### 3.3 Implementation References Document key resources for implementation: - Existing code files to reference or modify - Documentation links for technologies used - Code examples from research - Patterns to follow from the codebase - Libraries or dependencies to add ## Step 4: Create the Plan Document Write a comprehensive plan to `PRPs/[feature-name].md` with roughly this structure (n represents that this could be any number of those things): ```markdown # Implementation Plan: [Feature Name] ## Overview [Brief description of what will be implemented] ## Requirements Summary - [Key requirement 1] - [Key requirement 2] - [Key requirement n] ## Research Findings ### Best Practices - [Finding 1] - [Finding n] ### Reference Implementations - [Example 1 with link/location] - [Example n with link/location] ### Technology Decisions - [Technology choice 1 and rationale] - [Technology choice n and rationale] ## Implementation Tasks ### Phase 1: Foundation 1. **Task Name** - Description: [What needs to be done] - Files to modify/create: [List files] - Dependencies: [Any prerequisites] - Estimated effort: [time estimate] 2. **Task Name** - Description: [What needs to be done] - Files to modify/create: [List files] - Dependencies: [Any prerequisites] - Estimated effort: [time estimate] ### Phase 2: Core Implementation [Continue with numbered tasks...] ### Phase 3: Integration & Testing [Continue with numbered tasks...] ## Codebase Integration Points ### Files to Modify - `path/to/file1.js` - [What changes needed] - `path/to/filen.py` - [What changes needed] ### New Files to Create - `path/to/newfile1.js` - [Purpose] - `path/to/newfilen.py` - [Purpose] ### Existing Patterns to Follow - [Pattern 1 from codebase] - [Pattern n from codebase] ## Technical Design ### Architecture Diagram (if applicable) ``` [ASCII diagram or description] ``` ### Data Flow [Description of how data flows through the feature] ### API Endpoints (if applicable) - `POST /api/endpoint` - [Purpose] - `GET /api/endpoint/:id` - [Purpose] ## Dependencies and Libraries - [Library 1] - [Purpose] - [Library n] - [Purpose] ## Testing Strategy - Unit tests for [components] - Integration tests for [workflows] - Edge cases to cover: [list] ## Success Criteria - [ ] [Criterion 1] - [ ] [Criterion 2] - [ ] [Criterion n] ## Notes and Considerations - [Any important notes] - [Potential challenges] - [Future enhancements] --- *This plan is ready for execution with `/execute-plan`* ``` ## Step 5: Validation Before finalizing the plan: 1. Ensure all requirements are addressed 2. Verify tasks are properly sequenced 3. Check that integration points are identified 4. Confirm research supports the approach 5. Make sure the plan is actionable and clear ## Important Guidelines - **Be thorough in research**: The quality of the plan depends on understanding best practices - **Keep it actionable**: Every task should be clear and implementable - **Reference everything**: Include links, file paths, and examples - **Consider the existing codebase**: Follow established patterns and conventions - **Think about testing**: Include testing tasks in the plan - **Size tasks appropriately**: Not too large, not too granular ## Output Save the plan to the PRPs directory and inform the user: "Implementation plan created at: PRPs/[feature-name].md You can now execute this plan using: `/execute-plan PRPs/[feature-name].md`" ================================================ FILE: archon-example-workflow/.claude/commands/execute-plan.md ================================================ --- description: Execute a development plan with full Archon task management integration argument-hint: [plan-file-path] --- # Execute Development Plan with Archon Task Management You are about to execute a comprehensive development plan with integrated Archon task management. This workflow ensures systematic task tracking and implementation throughout the entire development process. ## Critical Requirements **MANDATORY**: Throughout the ENTIRE execution of this plan, you MUST maintain continuous usage of Archon for task management. DO NOT drop or skip Archon integration at any point. Every task from the plan must be tracked in Archon from creation to completion. ## Step 1: Read and Parse the Plan Read the plan file specified in: $ARGUMENTS The plan file will contain: - A list of tasks to implement - References to existing codebase components and integration points - Context about where to look in the codebase for implementation ## Step 2: Project Setup in Archon 1. Check if a project ID is specified in CLAUDE.md for this feature - Look for any Archon project references in CLAUDE.md - If found, use that project ID 2. If no project exists: - Create a new project in Archon using `mcp__archon__manage_project` - Use a descriptive title based on the plan's objectives - Store the project ID for use throughout execution ## Step 3: Create All Tasks in Archon For EACH task identified in the plan: 1. Create a corresponding task in Archon using `mcp__archon__manage_task("create", ...)` 2. Set initial status as "todo" 3. Include detailed descriptions from the plan 4. Maintain the task order/priority from the plan **IMPORTANT**: Create ALL tasks in Archon upfront before starting implementation. This ensures complete visibility of the work scope. ## Step 4: Codebase Analysis Before implementation begins: 1. Analyze ALL integration points mentioned in the plan 2. Use Grep and Glob tools to: - Understand existing code patterns - Identify where changes need to be made - Find similar implementations for reference 3. Read all referenced files and components 4. Build a comprehensive understanding of the codebase context ## Step 5: Implementation Cycle For EACH task in sequence: ### 5.1 Start Task - Move the current task to "doing" status in Archon: `mcp__archon__manage_task("update", task_id=..., status="doing")` - Use TodoWrite to track local subtasks if needed ### 5.2 Implement - Execute the implementation based on: - The task requirements from the plan - Your codebase analysis findings - Best practices and existing patterns - Make all necessary code changes - Ensure code quality and consistency ### 5.3 Complete Task - Once implementation is complete, move task to "review" status: `mcp__archon__manage_task("update", task_id=..., status="review")` - DO NOT mark as "done" yet - this comes after validation ### 5.4 Proceed to Next - Move to the next task in the list - Repeat steps 5.1-5.3 **CRITICAL**: Only ONE task should be in "doing" status at any time. Complete each task before starting the next. ## Step 6: Validation Phase After ALL tasks are in "review" status: **IMPORTANT: Use the `validator` agent for comprehensive testing** 1. Launch the validator agent using the Task tool - Provide the validator with a detailed description of what was built - Include the list of features implemented and files modified - The validator will create simple, effective unit tests - It will run tests and report results The validator agent will: - Create focused unit tests for the main functionality - Test critical edge cases and error handling - Run the tests using the project's test framework - Report what was tested and any issues found Additional validation you should perform: - Check for integration issues between components - Ensure all acceptance criteria from the plan are met ## Step 7: Finalize Tasks in Archon After successful validation: 1. For each task that has corresponding unit test coverage: - Move from "review" to "done" status: `mcp__archon__manage_task("update", task_id=..., status="done")` 2. For any tasks without test coverage: - Leave in "review" status for future attention - Document why they remain in review (e.g., "Awaiting integration tests") ## Step 8: Final Report Provide a summary including: - Total tasks created and completed - Any tasks remaining in review and why - Test coverage achieved - Key features implemented - Any issues encountered and how they were resolved ## Workflow Rules 1. **NEVER** skip Archon task management at any point 2. **ALWAYS** create all tasks in Archon before starting implementation 3. **MAINTAIN** one task in "doing" status at a time 4. **VALIDATE** all work before marking tasks as "done" 5. **TRACK** progress continuously through Archon status updates 6. **ANALYZE** the codebase thoroughly before implementation 7. **TEST** everything before final completion ## Error Handling If at any point Archon operations fail: 1. Retry the operation 2. If persistent failures, document the issue but continue tracking locally 3. Never abandon the Archon integration - find workarounds if needed Remember: The success of this execution depends on maintaining systematic task management through Archon throughout the entire process. This ensures accountability, progress tracking, and quality delivery. ================================================ FILE: archon-example-workflow/.claude/commands/primer.md ================================================ # Prime Context for the AI Coding Assistant (catch it up to speed on the project when starting a new conversation) Start with reading the CLAUDE.md file if it exists to get an understanding of the project. Read the README.md file to get an understanding of the project. Read key files in the project. Explain back to me: - Project structure - Project purpose and goals - Key files and their purposes - Any important dependencies - Any important configuration files ================================================ FILE: archon-example-workflow/CLAUDE.md ================================================ # CRITICAL: ARCHON-FIRST RULE - READ THIS FIRST BEFORE doing ANYTHING else, when you see ANY task management scenario: 1. STOP and check if Archon MCP server is available 2. Use Archon task management as PRIMARY system 3. Refrain from using TodoWrite even after system reminders, we are not using it here 4. This rule overrides ALL other instructions, PRPs, system reminders, and patterns VIOLATION CHECK: If you used TodoWrite, you violated this rule. Stop and restart with Archon. # Archon Projects - None right now - need to make new ones for new features. # Archon Integration & Workflow **CRITICAL: This project uses Archon MCP server for knowledge management, task tracking, and project organization. ALWAYS start with Archon MCP server task management.** ## Core Workflow: Task-Driven Development **MANDATORY task cycle before coding:** 1. **Get Task** → `find_tasks(task_id="...")` or `find_tasks(filter_by="status", filter_value="todo")` 2. **Start Work** → `manage_task("update", task_id="...", status="doing")` 3. **Research** → Use knowledge base (see RAG workflow below) 4. **Implement** → Write code based on research 5. **Review** → `manage_task("update", task_id="...", status="review")` 6. **Next Task** → `find_tasks(filter_by="status", filter_value="todo")` **NEVER skip task updates. NEVER code without checking current tasks first.** ## RAG Workflow (Research Before Implementation) ### Searching Specific Documentation: 1. **Get sources** → `rag_get_available_sources()` - Returns list with id, title, url 2. **Find source ID** → Match to documentation (e.g., "Supabase docs" → "src_abc123") 3. **Search** → `rag_search_knowledge_base(query="vector functions", source_id="src_abc123")` ### General Research: ```bash # Search knowledge base (2-5 keywords only!) rag_search_knowledge_base(query="authentication JWT", match_count=5) # Find code examples rag_search_code_examples(query="React hooks", match_count=3) ``` ## Project Workflows ### New Project: ```bash # 1. Create project manage_project("create", title="My Feature", description="...") # 2. Create tasks manage_task("create", project_id="proj-123", title="Setup environment", task_order=10) manage_task("create", project_id="proj-123", title="Implement API", task_order=9) ``` ### Existing Project: ```bash # 1. Find project find_projects(query="auth") # or find_projects() to list all # 2. Get project tasks find_tasks(filter_by="project", filter_value="proj-123") # 3. Continue work or create new tasks ``` ## Tool Reference **Projects:** - `find_projects(query="...")` - Search projects - `find_projects(project_id="...")` - Get specific project - `manage_project("create"/"update"/"delete", ...)` - Manage projects **Tasks:** - `find_tasks(query="...")` - Search tasks by keyword - `find_tasks(task_id="...")` - Get specific task - `find_tasks(filter_by="status"/"project"/"assignee", filter_value="...")` - Filter tasks - `manage_task("create"/"update"/"delete", ...)` - Manage tasks **Knowledge Base:** - `rag_get_available_sources()` - List all sources - `rag_search_knowledge_base(query="...", source_id="...")` - Search docs - `rag_search_code_examples(query="...", source_id="...")` - Find code ## Important Notes - Task status flow: `todo` → `doing` → `review` → `done` - Keep queries SHORT (2-5 keywords) for better search results - Higher `task_order` = higher priority (0-100) - Tasks should be 30 min - 4 hours of work ================================================ FILE: archon-example-workflow/README.md ================================================ # Archon AI Coding Workflow Template A simple yet reliable template for systematic AI-assisted development using **create-plan** and **execute-plan** workflows, powered by [Archon](https://github.com/coleam00/Archon) - the open-source AI coding command center. Build on top of this and create your own AI coding workflows! ## What is This? This is a reusable workflow template that brings structure and reliability to AI coding assistants. Instead of ad-hoc prompting, you get: - **Systematic planning** from requirements to implementation - **Knowledge-augmented development** via Archon's RAG capabilities - **Task management integration** for progress tracking - **Specialized subagents** for analysis and validation - **Codebase consistency** through pattern analysis Works with **Claude Code**, **Cursor**, **Windsurf**, **Codex**, and any AI coding assistant that supports custom commands or prompt templates. ## Core Workflows ### 1. Create Plan (`/create-plan`) Transform requirements into actionable implementation plans through systematic research and analysis. **What it does:** - Reads your requirements document - Searches Archon's knowledge base for best practices and patterns - Analyzes your codebase using the `codebase-analyst` subagent - Produces a comprehensive implementation plan (PRP) with: - Task breakdown with dependencies and effort estimates - Technical architecture and integration points - Code references and patterns to follow - Testing strategy and success criteria **Usage:** ```bash /create-plan requirements/my-feature.md ``` ### 2. Execute Plan (`/execute-plan`) Execute implementation plans with integrated Archon task management and validation. **What it does:** - Reads your implementation plan - Creates an Archon project and tasks automatically - Implements each task systematically (`todo` → `doing` → `review` → `done`) - Validates with the `validator` subagent to create unit tests - Tracks progress throughout with full visibility **Usage:** ```bash /execute-plan PRPs/my-feature.md ``` ## Why Archon? [Archon](https://github.com/coleam00/Archon) is an open-source AI coding OS that provides: - **Knowledge Base**: RAG-powered search across documentation, PDFs, and crawled websites - **Task Management**: Hierarchical projects with AI-assisted task creation and tracking - **Smart Search**: Hybrid search with contextual embeddings and reranking - **Multi-Agent Support**: Connect multiple AI assistants to shared context - **Model Context Protocol**: Standard MCP server for seamless integration Think of it as the command center that keeps your AI coding assistant informed and organized. ## What's Included ``` .claude/ ├── commands/ │ ├── create-plan.md # Requirements → Implementation plan │ ├── execute-plan.md # Plan → Tracked implementation │ └── primer.md # Project context loader ├── agents/ │ ├── codebase-analyst.md # Pattern analysis specialist │ └── validator.md # Testing specialist └── CLAUDE.md # Archon-first workflow rules ``` ## Setup Instructions ### For Claude Code 1. **Copy the template to your project:** ```bash cp -r use-cases/archon-example-workflow/.claude /path/to/your-project/ ``` 2. **Install Archon MCP server** (if not already installed): - Follow instructions at [github.com/coleam00/Archon](https://github.com/coleam00/Archon) - Configure in your Claude Code settings 3. **Start using workflows:** ```bash # In Claude Code /create-plan requirements/your-feature.md # Review the generated plan, then: /execute-plan PRPs/your-feature.md ``` ### For Other AI Assistants The workflows are just markdown prompt templates - adapt them to your tool - examples: #### **Cursor / Windsurf** - Copy files to `.cursor/` or `.windsurf/` directory - Use as custom commands or rules files - Manually invoke workflows by copying prompt content #### **Cline / Aider / Continue.dev** - Save workflows as prompt templates - Reference them in your session context - Adapt the MCP tool calls to your tool's API #### **Generic Usage** Even without tool-specific integrations: 1. Read `create-plan.md` and follow its steps manually 2. Use Archon's web UI for task management if MCP isn't available 3. Adapt the workflow structure to your assistant's capabilities ## Workflow in Action ### New Project Example ```bash # 1. Write requirements echo "Build a REST API for user authentication" > requirements/auth-api.md # 2. Create plan /create-plan requirements/auth-api.md # → AI searches Archon knowledge base for JWT best practices # → AI analyzes your codebase patterns # → Generates PRPs/auth-api.md with 12 tasks # 3. Execute plan /execute-plan PRPs/auth-api.md # → Creates Archon project "Authentication API" # → Creates 12 tasks in Archon # → Implements task-by-task with status tracking # → Runs validator subagent for unit tests # → Marks tasks done as they complete ``` ### Existing Project Example ```bash # 1. Create feature requirements # 2. Run create-plan (it analyzes existing codebase) /create-plan requirements/new-feature.md # → Discovers existing patterns from your code # → Suggests integration points # → Follows your project's conventions # 3. Execute with existing Archon project # Edit execute-plan.md to reference project ID or let it create new one /execute-plan PRPs/new-feature.md ``` ## Key Benefits ### For New Projects - **Pattern establishment**: AI learns and documents your conventions - **Structured foundation**: Plans prevent scope creep and missed requirements - **Knowledge integration**: Leverage best practices from day one ### For Existing Projects - **Convention adherence**: Codebase analysis ensures consistency - **Incremental enhancement**: Add features that fit naturally - **Context retention**: Archon keeps project history and patterns ## Customization ### Adapt the Workflows Edit the markdown files to match your needs - examples: - **Change task granularity** in `create-plan.md` (Step 3.1) - **Add custom validation** in `execute-plan.md` (Step 6) - **Modify report format** in either workflow - **Add your own subagents** for specialized tasks ### Extend with Subagents Create new specialized agents in `.claude/agents/`: ```markdown --- name: "security-auditor" description: "Reviews code for security vulnerabilities" tools: Read, Grep, Bash --- You are a security specialist who reviews code for... ``` Then reference in your workflows. ================================================ FILE: archon-ui-main/.dockerignore ================================================ # Dependencies node_modules npm-debug.log* yarn-debug.log* yarn-error.log* # Build output dist build # Environment variables .env .env.local .env.development.local .env.test.local .env.production.local # IDE and editor files .vscode .idea *.swp *.swo *~ # OS generated files .DS_Store .DS_Store? ._* .Spotlight-V100 .Trashes ehthumbs.db Thumbs.db # Git .git .gitignore # Docker Dockerfile docker-compose.yml .dockerignore # Tests coverage test-results tests/ **/*.test.ts **/*.test.tsx **/*.spec.ts **/*.spec.tsx **/__tests__ **/*.e2e.test.ts **/*.integration.test.ts vitest.config.ts tsconfig.prod.json # Documentation README.md *.md ================================================ FILE: archon-ui-main/.eslintrc.cjs ================================================ module.exports = { root: true, env: { browser: true, es2020: true, node: true }, extends: [ 'eslint:recommended', 'plugin:@typescript-eslint/recommended', 'plugin:react-hooks/recommended', ], ignorePatterns: [ 'dist', '.eslintrc.cjs', 'public', '__mocks__', '*.config.js', '*.config.ts', 'coverage', 'node_modules', 'src/features/**' // Biome handles this directory ], parser: '@typescript-eslint/parser', parserOptions: { ecmaVersion: 'latest', sourceType: 'module', }, plugins: ['react-refresh'], rules: { /** * LINTING STRATEGY FOR BETA DEVELOPMENT: * * Development: Warnings don't block local development, allowing rapid iteration * CI/PR: Run with --max-warnings 0 to treat warnings as errors before merge * * Philosophy: * - Strict typing where it helps AI assistants (Claude Code, Copilot, etc.) * - Pragmatic flexibility for beta-stage rapid development * - Console.log allowed locally but caught in CI * - Progressive enhancement: stricter rules in /features (new code) vs /components (legacy) */ // React Refresh 'react-refresh/only-export-components': [ 'warn', { allowConstantExport: true }, ], // TypeScript - Pragmatic strictness for AI-assisted development '@typescript-eslint/no-explicit-any': 'warn', // Visible but won't block development '@typescript-eslint/no-non-null-assertion': 'warn', // Allow when developer is certain '@typescript-eslint/no-empty-function': 'warn', // Sometimes needed for placeholders '@typescript-eslint/ban-types': 'error', // Keep strict - prevents real issues // Help AI assistants understand code intent '@typescript-eslint/explicit-function-return-type': ['warn', { allowExpressions: true, allowTypedFunctionExpressions: true, allowHigherOrderFunctions: true, allowDirectConstAssertionInArrowFunctions: true, }], // Better TypeScript patterns '@typescript-eslint/prefer-as-const': 'error', // Variable and import management - strict with escape hatches '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_', varsIgnorePattern: '^_', ignoreRestSiblings: true, destructuredArrayIgnorePattern: '^_' }], // React hooks - warn to allow intentional omissions during development 'react-hooks/exhaustive-deps': 'warn', // Console usage - warn locally, CI treats as error 'no-console': ['warn', { allow: ['error', 'warn'] }], // console.log caught but not blocking // General code quality 'prefer-const': 'error', 'no-var': 'error', 'no-constant-condition': 'error', 'no-debugger': 'warn', // Warn in dev, error in CI 'no-alert': 'error', // Disable rules that conflict with TypeScript 'no-undef': 'off', // TypeScript handles this better 'no-unused-vars': 'off', // Use @typescript-eslint/no-unused-vars instead }, // Override rules for specific file types and directories overrides: [ { // Stricter rules for new vertical slice architecture files: ['src/features/**/*.{ts,tsx}'], rules: { '@typescript-eslint/no-explicit-any': 'error', // No any in new code '@typescript-eslint/explicit-function-return-type': ['error', { allowExpressions: true, allowTypedFunctionExpressions: true, }], 'no-console': ['error', { allow: ['error', 'warn'] }], // Stricter console usage } }, { // More lenient for legacy components being migrated files: ['src/components/**/*.{ts,tsx}', 'src/services/**/*.{ts,tsx}'], rules: { '@typescript-eslint/no-explicit-any': 'warn', // Still visible during migration '@typescript-eslint/explicit-function-return-type': 'off', // Not required for legacy 'no-console': 'warn', // Warn during migration } }, { // Test files - most lenient but still helpful files: ['**/*.test.{ts,tsx}', '**/*.spec.{ts,tsx}', 'test/**/*'], rules: { '@typescript-eslint/no-explicit-any': 'warn', // OK in tests but still visible '@typescript-eslint/no-non-null-assertion': 'off', // Fine in tests '@typescript-eslint/no-empty-function': 'off', // Mock functions need this '@typescript-eslint/explicit-function-return-type': 'off', 'no-console': 'off', // Debugging in tests is fine } } ] }; ================================================ FILE: archon-ui-main/.gitignore ================================================ # Logs logs *.log npm-debug.log* yarn-debug.log* yarn-error.log* pnpm-debug.log* lerna-debug.log* node_modules dist dist-ssr *.local # Test coverage coverage .nyc_output public/test-results test-results.json # Editor directories and files .vscode/* !.vscode/extensions.json .idea .DS_Store *.suo *.ntvs* *.njsproj *.sln *.sw? ================================================ FILE: archon-ui-main/Dockerfile ================================================ # Simple Vite dev server setup FROM node:18-alpine WORKDIR /app # Install system dependencies needed for some npm packages RUN apk add --no-cache python3 make g++ git curl # Copy package files COPY package*.json ./ # Install dependencies including dev dependencies for testing RUN npm ci # Create coverage directory with proper permissions RUN mkdir -p /app/coverage && chmod 777 /app/coverage # Copy source code COPY . . # Expose the port configured in package.json (3737) EXPOSE 3737 # Start Vite dev server (already configured with --port 3737 --host in package.json) CMD ["npm", "run", "dev"] ================================================ FILE: archon-ui-main/README.md ================================================ # Archon UI - Knowledge Engine Web Interface A modern React-based web interface for the Archon Knowledge Engine MCP Server. Built with TypeScript, Vite, and Tailwind CSS. ## 🎨 UI Overview Archon UI provides a comprehensive dashboard for managing your AI's knowledge base: ![UI Architecture](https://via.placeholder.com/800x400?text=Archon+UI+Architecture) ### Key Features - **📊 MCP Dashboard**: Monitor and control the MCP server - **⚙️ Settings Management**: Configure credentials and RAG strategies - **🕷️ Web Crawling**: Crawl documentation sites and build knowledge base - **📚 Knowledge Management**: Browse, search, and organize knowledge items - **💬 Interactive Chat**: Test RAG queries with real-time responses - **📈 Real-time Updates**: WebSocket-based live updates across the UI ## 🏗️ Architecture ### Technology Stack - **React 18.3**: Modern React with hooks and functional components - **TypeScript**: Full type safety and IntelliSense support - **Vite**: Fast build tool and dev server - **Tailwind CSS**: Utility-first styling - **Framer Motion**: Smooth animations and transitions - **Lucide Icons**: Beautiful and consistent iconography - **React Router**: Client-side routing ### Project Structure ``` archon-ui-main/ ├── src/ │ ├── components/ # Reusable UI components │ │ ├── ui/ # Base UI components (Button, Card, etc.) │ │ ├── layouts/ # Layout components (Sidebar, Header) │ │ └── animations/ # Animation components │ ├── pages/ # Page components │ │ ├── MCPPage.tsx # MCP Dashboard │ │ ├── Settings.tsx # Settings page │ │ ├── Crawl.tsx # Web crawling interface │ │ ├── KnowledgeBase.tsx # Knowledge management │ │ └── Chat.tsx # RAG chat interface │ ├── services/ # API and service layers │ │ ├── api.ts # Base API configuration │ │ ├── mcpService.ts # MCP server communication │ │ └── chatService.ts # Chat/RAG service │ ├── contexts/ # React contexts │ │ └── ToastContext.tsx # Toast notifications │ ├── hooks/ # Custom React hooks │ │ └── useStaggeredEntrance.ts # Animation hook │ ├── types/ # TypeScript type definitions │ └── lib/ # Utility functions ├── public/ # Static assets └── test/ # Test files ``` ## 📄 Pages Documentation ### 1. MCP Dashboard (`/mcp`) The central control panel for the MCP server. **Components:** - **Server Control Panel**: Start/stop server, view status, select transport mode - **Server Logs Viewer**: Real-time log streaming with auto-scroll - **Available Tools Table**: Dynamic tool discovery and documentation - **MCP Test Panel**: Interactive tool testing interface **Features:** - Dual transport support (SSE/stdio) - Real-time status polling (5-second intervals) - WebSocket-based log streaming - Copy-to-clipboard configuration - Tool parameter validation ### 2. Settings (`/settings`) Comprehensive configuration management. **Sections:** - **Credentials**: - OpenAI API key (encrypted storage) - Supabase connection details - MCP server configuration - **RAG Strategies**: - Contextual Embeddings toggle - Hybrid Search toggle - Agentic RAG (code extraction) toggle - Reranking toggle **Features:** - Secure credential storage with encryption - Real-time validation - Toast notifications for actions - Default value management ### 3. Web Crawling (`/crawl`) Interface for crawling documentation sites. **Components:** - **URL Input**: Smart URL validation - **Crawl Options**: Max depth, concurrent sessions - **Progress Monitoring**: Real-time crawl status - **Results Summary**: Pages crawled, chunks stored **Features:** - Intelligent URL type detection - Sitemap support - Recursive crawling - Batch processing ### 4. Knowledge Base (`/knowledge`) Browse and manage your knowledge items. **Components:** - **Knowledge Grid**: Card-based knowledge display - **Search/Filter**: Search by title, type, tags - **Knowledge Details**: View full item details - **Actions**: Delete, refresh, organize **Features:** - Pagination support - Real-time updates via WebSocket - Type-based filtering (technical/business) - Metadata display ### 5. RAG Chat (`/chat`) Interactive chat interface for testing RAG queries. **Components:** - **Chat Messages**: Threaded conversation view - **Input Area**: Query input with source selection - **Results Display**: Formatted RAG results - **Source Selector**: Filter by knowledge source **Features:** - Real-time streaming responses - Source attribution - Markdown rendering - Copy functionality ## 🧩 Component Library ### Base UI Components #### Button ```tsx ``` #### Card ```tsx

Card Title

Card content

 ``` #### LoadingSpinner ```tsx ``` ### Layout Components #### Sidebar - Collapsible navigation - Active route highlighting - Icon + text navigation items - Responsive design #### Header - Dark mode toggle - User menu - Breadcrumb navigation ### Animation Components #### PageTransition Wraps pages with smooth fade/slide animations: ```tsx ``` ## 🔌 Services ### mcpService Handles all MCP server communication: - `startServer()`: Start the MCP server - `stopServer()`: Stop the MCP server - `getStatus()`: Get current server status - `streamLogs()`: WebSocket log streaming - `getAvailableTools()`: Fetch MCP tools ### api Base API configuration with: - Automatic error handling - Request/response interceptors - Base URL configuration - TypeScript generics ### chatService RAG query interface: - `sendMessage()`: Send RAG query - `streamResponse()`: Stream responses - `getSources()`: Get available sources ## 🎨 Styling ### Tailwind Configuration - Custom color palette - Dark mode support - Custom animations - Responsive breakpoints ### Theme Variables ```css --primary: Blue accent colors --secondary: Gray/neutral colors --success: Green indicators --warning: Orange indicators --error: Red indicators ``` ## 🚀 Development ### Setup ```bash # Install dependencies npm install # Start dev server npm run dev # Build for production npm run build # Run tests npm test ``` ### Environment Variables ```env VITE_API_URL=http://localhost:8080 ``` ### Hot Module Replacement Vite provides instant HMR for: - React components - CSS modules - TypeScript files ## 🧪 Testing ### Unit Tests - Component testing with React Testing Library - Service mocking with MSW - Hook testing with @testing-library/react-hooks ### Integration Tests - Page-level testing - API integration tests - WebSocket testing ## 📦 Build & Deployment ### Docker Support ```dockerfile FROM node:18-alpine WORKDIR /app COPY package*.json ./ RUN npm ci COPY . . RUN npm run build EXPOSE 5173 CMD ["npm", "run", "preview"] ``` ### Production Optimization - Code splitting by route - Lazy loading for pages - Image optimization - Bundle size analysis ## 🔧 Configuration Files ### vite.config.ts - Path aliases - Build optimization - Development server config ### tsconfig.json - Strict type checking - Path mappings - Compiler options ### tailwind.config.js - Custom theme - Plugin configuration - Purge settings ## 🤝 Contributing ### Code Style - ESLint configuration - Prettier formatting - TypeScript strict mode - Component naming conventions ### Git Workflow - Feature branches - Conventional commits - PR templates - Code review process ================================================ FILE: archon-ui-main/biome.json ================================================ { "$schema": "https://biomejs.dev/schemas/2.2.2/schema.json", "files": { "includes": ["src/features/**", "src/components/layout/**"] }, "formatter": { "enabled": true, "indentStyle": "space", "indentWidth": 2, "lineWidth": 120, "bracketSpacing": true, "attributePosition": "auto" }, "javascript": { "formatter": { "quoteStyle": "double", "jsxQuoteStyle": "double", "quoteProperties": "asNeeded", "trailingCommas": "all", "semicolons": "always", "arrowParentheses": "always", "bracketSameLine": false } }, "linter": { "enabled": true, "rules": { "recommended": true } }, "assist": { "enabled": true, "actions": { "source": { "organizeImports": { "level": "on" } } } } } ================================================ FILE: archon-ui-main/index.html ================================================ Archon - Knowledge Engine
================================================ FILE: archon-ui-main/package.json ================================================ { "name": "archon-ui", "version": "0.1.0", "private": true, "type": "module", "scripts": { "dev": "npx vite", "build": "npx vite build", "lint": "eslint . --ext .js,.jsx,.ts,.tsx", "lint:files": "eslint --ext .js,.jsx,.ts,.tsx", "biome": "biome check", "biome:fix": "biome check --write", "biome:format": "biome format --write", "biome:lint": "biome lint", "biome:ai": "biome check --reporter=json", "biome:ai-fix": "biome check --write --reporter=json", "biome:ci": "biome ci", "preview": "npx vite preview", "test": "vitest", "test:run": "vitest run", "test:ui": "vitest --ui", "test:integration": "vitest run --config vitest.integration.config.ts", "test:coverage": "npm run test:coverage:run && npm run test:coverage:summary", "test:coverage:run": "vitest run --coverage --reporter=dot --reporter=json", "test:coverage:stream": "vitest run --coverage --reporter=default --reporter=json --bail=false || true", "test:coverage:summary": "echo '\\n📊 ARCHON TEST & COVERAGE SUMMARY\\n═══════════════════════════════════════\\n' && node -e \"try { const data = JSON.parse(require('fs').readFileSync('coverage/test-results.json', 'utf8')); const passed = data.numPassedTests || 0; const failed = data.numFailedTests || 0; const total = data.numTotalTests || 0; const suites = data.numTotalTestSuites || 0; console.log('Test Suites: ' + (failed > 0 ? '\\x1b[31m' + failed + ' failed\\x1b[0m, ' : '') + '\\x1b[32m' + (suites - failed) + ' passed\\x1b[0m, ' + suites + ' total'); console.log('Tests: ' + (failed > 0 ? '\\x1b[31m' + failed + ' failed\\x1b[0m, ' : '') + '\\x1b[32m' + passed + ' passed\\x1b[0m, ' + total + ' total'); console.log('\\n✨ Results saved to coverage/test-results.json'); } catch(e) { console.log('⚠️ No test results found. Run tests first!'); }\" || true", "test:coverage:force": "vitest run --coverage --passWithNoTests || true", "seed:projects": "node --loader ts-node/esm ../scripts/seed-project-data.ts" }, "dependencies": { "@mdxeditor/editor": "^3.42.0", "@radix-ui/react-alert-dialog": "^1.1.15", "@radix-ui/react-checkbox": "^1.3.3", "@radix-ui/react-dialog": "^1.1.15", "@radix-ui/react-dropdown-menu": "^2.1.16", "@radix-ui/react-label": "^2.1.7", "@radix-ui/react-popover": "^1.1.15", "@radix-ui/react-radio-group": "^1.3.8", "@radix-ui/react-select": "^2.2.6", "@radix-ui/react-switch": "^1.2.6", "@radix-ui/react-tabs": "^1.1.13", "@radix-ui/react-toast": "^1.2.15", "@radix-ui/react-tooltip": "^1.2.8", "@tanstack/react-query": "^5.85.8", "@tanstack/react-query-devtools": "^5.85.8", "clsx": "latest", "date-fns": "^4.1.0", "fractional-indexing": "^3.2.0", "framer-motion": "^11.5.4", "lucide-react": "^0.441.0", "nanoid": "^5.0.9", "prismjs": "^1.30.0", "react": "^18.3.1", "react-dnd": "^16.0.1", "react-dnd-html5-backend": "^16.0.1", "react-dom": "^18.3.1", "react-icons": "^5.5.0", "react-markdown": "^10.1.0", "react-router-dom": "^6.26.2", "tailwind-merge": "latest", "zod": "^3.25.46", "zustand": "^5.0.8" }, "devDependencies": { "@biomejs/biome": "2.2.2", "@tailwindcss/postcss": "4.1.2", "@tailwindcss/vite": "4.1.2", "@testing-library/jest-dom": "^6.4.6", "@testing-library/react": "^14.3.1", "@testing-library/user-event": "^14.5.2", "@types/node": "^20.19.0", "@types/prismjs": "^1.26.5", "@types/react": "^18.3.1", "@types/react-dom": "^18.3.1", "@typescript-eslint/eslint-plugin": "^6.21.0", "@typescript-eslint/parser": "^6.21.0", "@vitejs/plugin-react": "^4.2.1", "@vitest/coverage-v8": "^1.6.0", "@vitest/ui": "^1.6.0", "autoprefixer": "latest", "eslint": "^8.57.1", "eslint-plugin-react-hooks": "^4.6.0", "eslint-plugin-react-refresh": "^0.4.1", "jsdom": "^24.1.0", "postcss": "latest", "tailwindcss": "4.1.2", "ts-node": "^10.9.1", "typescript": "^5.5.4", "vite": "^5.2.0", "vitest": "^1.6.0" } } ================================================ FILE: archon-ui-main/postcss.config.js ================================================ export default { plugins: { '@tailwindcss/postcss': {}, autoprefixer: {}, }, } ================================================ FILE: archon-ui-main/src/App.tsx ================================================ import { useState, useEffect } from 'react'; import { BrowserRouter as Router, Routes, Route, Navigate } from 'react-router-dom'; import { QueryClientProvider } from '@tanstack/react-query'; import { ReactQueryDevtools } from '@tanstack/react-query-devtools'; import { queryClient } from './features/shared/config/queryClient'; import { KnowledgeBasePage } from './pages/KnowledgeBasePage'; import { SettingsPage } from './pages/SettingsPage'; import { MCPPage } from './pages/MCPPage'; import { OnboardingPage } from './pages/OnboardingPage'; import { MainLayout } from './components/layout/MainLayout'; import { ThemeProvider } from './contexts/ThemeContext'; import { ToastProvider } from './features/ui/components/ToastProvider'; import { SettingsProvider, useSettings } from './contexts/SettingsContext'; import { TooltipProvider } from './features/ui/primitives/tooltip'; import { ProjectPage } from './pages/ProjectPage'; import StyleGuidePage from './pages/StyleGuidePage'; import { AgentWorkOrdersPage } from './pages/AgentWorkOrdersPage'; import { AgentWorkOrderDetailPage } from './pages/AgentWorkOrderDetailPage'; import { DisconnectScreenOverlay } from './components/DisconnectScreenOverlay'; import { ErrorBoundaryWithBugReport } from './components/bug-report/ErrorBoundaryWithBugReport'; import { MigrationBanner } from './components/ui/MigrationBanner'; import { serverHealthService } from './services/serverHealthService'; import { useMigrationStatus } from './hooks/useMigrationStatus'; const AppRoutes = () => { const { projectsEnabled, styleGuideEnabled, agentWorkOrdersEnabled } = useSettings(); return ( } /> } /> } /> } /> {styleGuideEnabled ? ( } /> ) : ( } /> )} {projectsEnabled ? ( <> } /> } /> ) : ( } /> )} {agentWorkOrdersEnabled ? ( <> } /> } /> ) : ( } /> )} ); }; const AppContent = () => { const [disconnectScreenActive, setDisconnectScreenActive] = useState(false); const [disconnectScreenDismissed, setDisconnectScreenDismissed] = useState(false); const [disconnectScreenSettings, setDisconnectScreenSettings] = useState({ enabled: true, delay: 10000 }); const [migrationBannerDismissed, setMigrationBannerDismissed] = useState(false); const migrationStatus = useMigrationStatus(); useEffect(() => { // Load initial settings const settings = serverHealthService.getSettings(); setDisconnectScreenSettings(settings); // Stop any existing monitoring before starting new one to prevent multiple intervals serverHealthService.stopMonitoring(); // Start health monitoring serverHealthService.startMonitoring({ onDisconnected: () => { if (!disconnectScreenDismissed) { setDisconnectScreenActive(true); } }, onReconnected: () => { setDisconnectScreenActive(false); setDisconnectScreenDismissed(false); // Refresh the page to ensure all data is fresh window.location.reload(); } }); return () => { serverHealthService.stopMonitoring(); }; }, [disconnectScreenDismissed]); const handleDismissDisconnectScreen = () => { setDisconnectScreenActive(false); setDisconnectScreenDismissed(true); }; return ( <> {/* Migration Banner - shows when backend is up but DB schema needs work */} {migrationStatus.migrationRequired && !migrationBannerDismissed && ( setMigrationBannerDismissed(true)} /> )} ); }; export function App() { return ( {import.meta.env.VITE_SHOW_DEVTOOLS === 'true' && ( )} ); } ================================================ FILE: archon-ui-main/src/components/BackendStartupError.tsx ================================================ import React from 'react'; import { AlertCircle, Terminal, RefreshCw } from 'lucide-react'; export const BackendStartupError: React.FC = () => { const handleRetry = () => { // Reload the page to retry window.location.reload(); }; return (

Backend Service Startup Failure

The Archon backend service failed to start. This is typically due to a configuration issue.

Check Docker Logs

Check the Archon API server container logs in Docker Desktop for detailed error information.

1. Open Docker Desktop

2. Go to Containers tab

3. Look for the Archon server container (typically named archon-server or similar)

4. View the logs for the specific error message

Common issues:

  • Using an ANON key instead of SERVICE key in your .env file
  • Database not set up - run migration/complete_setup.sql in Supabase SQL Editor

After fixing the issue in your .env file, recreate the Docker containers:

docker compose down && docker compose up --build -d

Note:

• Use 'down' and 'up' (not 'restart') so new env vars are picked up.

• If you originally started with a specific profile (backend, frontend, or full),

  run the same profile again:


docker compose --profile full up --build -d
); }; ================================================ FILE: archon-ui-main/src/components/DisconnectScreenOverlay.tsx ================================================ import React, { useState } from 'react'; import { X, Wifi, WifiOff } from 'lucide-react'; import { DisconnectScreen } from './animations/DisconnectScreenAnimations'; import { NeonButton } from './ui/NeonButton'; interface DisconnectScreenOverlayProps { isActive: boolean; onDismiss?: () => void; } export const DisconnectScreenOverlay: React.FC = ({ isActive, onDismiss }) => { const [showControls, setShowControls] = useState(false); if (!isActive) return null; return (
setShowControls(true)} onMouseEnter={() => setShowControls(true)} onMouseLeave={() => setTimeout(() => setShowControls(false), 3000)} > {/* Disconnect Screen Animation */} {/* Override Button */}
{onDismiss && ( Dismiss )}
); }; ================================================ FILE: archon-ui-main/src/components/agent-chat/ArchonChatPanel.tsx ================================================ import React, { useEffect, useState, useRef } from 'react'; import { Send, User, WifiOff, RefreshCw, BookOpen, Search } from 'lucide-react'; import { ArchonLoadingSpinner, EdgeLitEffect } from '../animations/Animations'; import { agentChatService, ChatMessage } from '../../services/agentChatService'; /** * Props for the ArchonChatPanel component */ interface ArchonChatPanelProps { 'data-id'?: string; } /** * ArchonChatPanel - A chat interface for the Archon AI assistant * * This component provides a resizable chat panel with message history, * loading states, and input functionality connected to real AI agents. */ export const ArchonChatPanel: React.FC = props => { // State for messages, session, and other chat functionality const [messages, setMessages] = useState([]); const [sessionId, setSessionId] = useState(null); const [isInitialized, setIsInitialized] = useState(false); // State for input field, panel width, loading state, and dragging state const [inputValue, setInputValue] = useState(''); const [width, setWidth] = useState(416); // Default width - increased by 30% from 320px const [isTyping, setIsTyping] = useState(false); const [isDragging, setIsDragging] = useState(false); const [connectionError, setConnectionError] = useState(null); const [streamingMessage, setStreamingMessage] = useState(''); const [isStreaming, setIsStreaming] = useState(false); // Add connection status state const [connectionStatus, setConnectionStatus] = useState<'online' | 'offline' | 'connecting'>('connecting'); const [isReconnecting, setIsReconnecting] = useState(false); // No agent switching - always use RAG // Refs for DOM elements const messagesEndRef = useRef(null); const dragHandleRef = useRef(null); const chatPanelRef = useRef(null); const sessionIdRef = useRef(null); /** * Initialize chat session and connection */ const initializeChat = React.useCallback(async () => { try { setConnectionStatus('connecting'); // Yield to next frame to avoid initialization race conditions await new Promise(resolve => requestAnimationFrame(resolve)); // Create a new chat session try { console.log(`[CHAT PANEL] Creating session with agentType: "rag"`); const { session_id } = await agentChatService.createSession(undefined, 'rag'); console.log(`[CHAT PANEL] Session created with ID: ${session_id}`); setSessionId(session_id); sessionIdRef.current = session_id; // Load initial chat history try { const history = await agentChatService.getChatHistory(session_id); console.log(`[CHAT PANEL] Loaded chat history:`, history); setMessages(history || []); } catch (error) { console.error('Failed to load chat history:', error); // Initialize with empty messages if history can't be loaded setMessages([]); } // Start polling for new messages (will fail gracefully if backend is down) try { await agentChatService.streamMessages( session_id, (message: ChatMessage) => { setMessages(prev => [...prev, message]); setConnectionError(null); // Clear any previous errors on successful message setConnectionStatus('online'); }, (error: Error) => { console.error('Message streaming error:', error); setConnectionStatus('offline'); setConnectionError('Chat service is offline. Messages will not be received.'); } ); } catch (error) { console.error('Failed to start message streaming:', error); // Continue anyway - the chat will work in offline mode } setIsInitialized(true); setConnectionStatus('online'); setConnectionError(null); } catch (error) { console.error('Failed to initialize chat session:', error); if (error instanceof Error && error.message.includes('not available')) { setConnectionError('Agent chat service is disabled. Enable it in docker-compose to use this feature.'); } else { setConnectionError('Failed to initialize chat. Server may be offline.'); } setConnectionStatus('offline'); } } catch (error) { console.error('Failed to initialize chat:', error); if (error instanceof Error && error.message.includes('not available')) { setConnectionError('Agent chat service is disabled. Enable it in docker-compose to use this feature.'); } else { setConnectionError('Failed to connect to agent. Server may be offline.'); } setConnectionStatus('offline'); } }, []); // Initialize on mount and when explicitly requested useEffect(() => { if (!isInitialized) { initializeChat(); } }, [isInitialized, initializeChat]); // Cleanup effect - only on unmount useEffect(() => { return () => { if (sessionIdRef.current) { console.log('[CHAT PANEL] Component unmounting, cleaning up session:', sessionIdRef.current); // Stop streaming messages when component unmounts agentChatService.stopStreaming(sessionIdRef.current); } }; }, []); // Empty deps = only on unmount /** * Handle resizing of the chat panel via drag */ useEffect(() => { // Handler for mouse movement during drag const handleMouseMove = (e: MouseEvent) => { if (isDragging && chatPanelRef.current) { const containerRect = chatPanelRef.current.parentElement?.getBoundingClientRect(); if (containerRect) { // Calculate new width based on mouse position (from right edge of screen) const newWidth = window.innerWidth - e.clientX; // Set min and max width constraints if (newWidth >= 280 && newWidth <= 600) { setWidth(newWidth); } } } }; // Handler for mouse up to end dragging const handleMouseUp = () => { setIsDragging(false); document.body.style.cursor = 'default'; document.body.style.userSelect = 'auto'; }; // Add event listeners when dragging if (isDragging) { document.addEventListener('mousemove', handleMouseMove); document.addEventListener('mouseup', handleMouseUp); document.body.style.cursor = 'ew-resize'; document.body.style.userSelect = 'none'; // Prevent text selection while dragging } // Clean up event listeners return () => { document.removeEventListener('mousemove', handleMouseMove); document.removeEventListener('mouseup', handleMouseUp); }; }, [isDragging]); /** * Handler for starting the drag operation */ const handleDragStart = (e: React.MouseEvent) => { e.preventDefault(); setIsDragging(true); }; /** * Auto-scroll to the bottom when messages change */ useEffect(() => { messagesEndRef.current?.scrollIntoView({ behavior: 'smooth' }); }, [messages, isTyping, streamingMessage]); /** * Handle sending a new message to the agent */ const handleSendMessage = async () => { if (!inputValue.trim() || !sessionId) return; try { // Add context for RAG agent const context = { match_count: 5, // Can add source_filter here if needed in the future }; // Send message to agent via service await agentChatService.sendMessage(sessionId, inputValue.trim(), context); setInputValue(''); setConnectionError(null); } catch (error) { console.error('Failed to send message:', error); setConnectionError('Failed to send message. Please try again.'); } }; /** * Format timestamp for display in messages */ const formatTime = (date: Date) => { return date.toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' }); }; /** * Handle manual reconnection */ const handleReconnect = async () => { if (!sessionId || isReconnecting) return; setIsReconnecting(true); setConnectionStatus('connecting'); setConnectionError('Attempting to reconnect...'); try { const success = await agentChatService.manualReconnect(sessionId); if (success) { setConnectionError(null); setConnectionStatus('online'); } else { setConnectionError('Reconnection failed. Server may still be offline.'); setConnectionStatus('offline'); } } catch (error) { console.error('Manual reconnection failed:', error); setConnectionError('Reconnection failed. Please try again later.'); setConnectionStatus('offline'); } finally { setIsReconnecting(false); } }; return (
{/* Drag handle for resizing */}
{/* Main panel with glassmorphism */}
{/* Edgelit glow effect */} {/* Header gradient background */}
{/* Header */}
{/* Archon Logo - No animation in header */}
Archon

Knowledge Base Assistant

{/* Connection status and controls */}
{/* Connection status indicator */} {connectionStatus === 'offline' && (
Chat Offline
)} {connectionStatus === 'connecting' && (
Connecting...
)} {connectionStatus === 'online' && !connectionError && (
Online
)} {/* Error message overlay */} {connectionError && connectionStatus !== 'offline' && (
{connectionError}
)}
{/* Messages area */}
{messages.map(message => (
{message.sender === 'agent' ? (
Archon
) : ( )} {formatTime(message.timestamp)}
{/* For RAG responses, handle markdown-style formatting */} {message.agent_type === 'rag' && message.sender === 'agent' ? (
{message.content.split('\n').map((line, idx) => { // Handle bold text const boldRegex = /\*\*(.*?)\*\*/g; const parts = line.split(boldRegex); return (
{parts.map((part, partIdx) => partIdx % 2 === 1 ? ( {part} ) : ( {part} ) )}
); })}
) : ( message.content )}
))} {/* Streaming message */} {isStreaming && streamingMessage && (
Archon
{formatTime(new Date())}

{streamingMessage}

)} {/* Typing indicator */} {(isTyping && !isStreaming) && (
Agent is typing...
)}
{/* Input area */}
{connectionStatus === 'offline' && (
Chat is currently offline. Please use the reconnect button above to try again.
)}
{/* Text input field */}
setInputValue(e.target.value)} placeholder={ connectionStatus === 'offline' ? "Chat is offline..." : connectionStatus === 'connecting' ? "Connecting..." : "Search the knowledge base..." } disabled={connectionStatus !== 'online'} className="w-full bg-transparent text-gray-800 dark:text-white placeholder:text-gray-500 dark:placeholder:text-zinc-600 focus:outline-none disabled:opacity-50" onKeyDown={e => { if (e.key === 'Enter') handleSendMessage(); }} />
{/* Send button */}
); }; ================================================ FILE: archon-ui-main/src/components/animations/Animations.tsx ================================================ import React from 'react'; /** * ArchonLoadingSpinner - A loading animation component with neon trail effects * * This component displays the Archon logo with animated spinning circles * that create a neon trail effect. It's used to indicate loading states * throughout the application. * * @param {Object} props - Component props * @param {string} props.size - Size variant ('sm', 'md', 'lg') * @param {string} props.logoSrc - Source URL for the logo image * @param {string} props.className - Additional CSS classes */ export const ArchonLoadingSpinner: React.FC<{ size?: 'sm' | 'md' | 'lg'; logoSrc?: string; className?: string; }> = ({ size = 'md', logoSrc = "/logo-neon.png", className = '' }) => { // Size mappings for the container and logo const sizeMap = { sm: { container: 'w-8 h-8', logo: 'w-5 h-5' }, md: { container: 'w-10 h-10', logo: 'w-7 h-7' }, lg: { container: 'w-14 h-14', logo: 'w-9 h-9' } }; return
{/* Central logo */} Loading {/* Animated spinning circles with neon trail effects */}
{/* First circle - cyan with clockwise rotation */}
{/* Second circle - fuchsia with counter-clockwise rotation */}
; }; /** * NeonGlowEffect - A component that adds a neon glow effect to its children * * This component creates a container with a neon glow effect in different colors. * It's used for highlighting UI elements with a cyberpunk/neon aesthetic. * * @param {Object} props - Component props * @param {React.ReactNode} props.children - Child elements * @param {string} props.color - Color variant ('cyan', 'fuchsia', 'blue', 'purple', 'green', 'pink') * @param {string} props.intensity - Glow intensity ('low', 'medium', 'high') * @param {string} props.className - Additional CSS classes */ export const NeonGlowEffect: React.FC<{ children: React.ReactNode; color?: 'cyan' | 'fuchsia' | 'blue' | 'purple' | 'green' | 'pink'; intensity?: 'low' | 'medium' | 'high'; className?: string; }> = ({ children, color = 'blue', intensity = 'medium', className = '' }) => { // Color mappings for different neon colors const colorMap = { cyan: 'border-cyan-400 shadow-cyan-400/50 dark:shadow-cyan-400/70', fuchsia: 'border-fuchsia-400 shadow-fuchsia-400/50 dark:shadow-fuchsia-400/70', blue: 'border-blue-400 shadow-blue-400/50 dark:shadow-blue-400/70', purple: 'border-purple-500 shadow-purple-500/50 dark:shadow-purple-500/70', green: 'border-emerald-500 shadow-emerald-500/50 dark:shadow-emerald-500/70', pink: 'border-pink-500 shadow-pink-500/50 dark:shadow-pink-500/70' }; // Intensity mappings for glow strength const intensityMap = { low: 'shadow-[0_0_5px_0]', medium: 'shadow-[0_0_10px_1px]', high: 'shadow-[0_0_15px_2px]' }; return
{children}
; }; /** * EdgeLitEffect - A component that adds an edge-lit glow effect * * This component creates a thin glowing line at the top of a container, * simulating the effect of edge lighting. * * @param {Object} props - Component props * @param {string} props.color - Color variant ('blue', 'purple', 'green', 'pink') * @param {string} props.className - Additional CSS classes */ export const EdgeLitEffect: React.FC<{ color?: 'blue' | 'purple' | 'green' | 'pink'; className?: string; }> = ({ color = 'blue', className = '' }) => { // Color mappings for different edge-lit colors const colorMap = { blue: 'bg-blue-500 shadow-[0_0_10px_2px_rgba(59,130,246,0.4)] dark:shadow-[0_0_20px_5px_rgba(59,130,246,0.7)]', purple: 'bg-purple-500 shadow-[0_0_10px_2px_rgba(168,85,247,0.4)] dark:shadow-[0_0_20px_5px_rgba(168,85,247,0.7)]', green: 'bg-emerald-500 shadow-[0_0_10px_2px_rgba(16,185,129,0.4)] dark:shadow-[0_0_20px_5px_rgba(16,185,129,0.7)]', pink: 'bg-pink-500 shadow-[0_0_10px_2px_rgba(236,72,153,0.4)] dark:shadow-[0_0_20px_5px_rgba(236,72,153,0.7)]' }; return
; }; ================================================ FILE: archon-ui-main/src/components/animations/DisconnectScreenAnimations.tsx ================================================ import React, { useEffect, useRef } from 'react'; /** * Disconnect Screen * Frosted glass medallion with aurora borealis light show behind it */ export const DisconnectScreen: React.FC = () => { const canvasRef = useRef(null); useEffect(() => { const canvas = canvasRef.current; if (!canvas) return; const ctx = canvas.getContext('2d'); if (!ctx) return; canvas.width = window.innerWidth; canvas.height = window.innerHeight; let time = 0; const drawAurora = () => { // Create dark background with vignette const gradient = ctx.createRadialGradient( canvas.width / 2, canvas.height / 2, 0, canvas.width / 2, canvas.height / 2, canvas.width / 1.5 ); gradient.addColorStop(0, 'rgba(0, 0, 0, 0.3)'); gradient.addColorStop(1, 'rgba(0, 0, 0, 0.95)'); ctx.fillStyle = gradient; ctx.fillRect(0, 0, canvas.width, canvas.height); // Draw aurora waves with varying opacity const colors = [ { r: 34, g: 211, b: 238, a: 0.4 }, // Cyan { r: 168, g: 85, b: 247, a: 0.4 }, // Purple { r: 236, g: 72, b: 153, a: 0.4 }, // Pink { r: 59, g: 130, b: 246, a: 0.4 }, // Blue { r: 16, g: 185, b: 129, a: 0.4 }, // Green ]; colors.forEach((color, index) => { ctx.beginPath(); const waveHeight = 250; const waveOffset = index * 60; const speed = 0.001 + index * 0.0002; // Animate opacity for ethereal effect const opacityWave = Math.sin(time * 0.0005 + index) * 0.2 + 0.3; for (let x = 0; x <= canvas.width; x += 5) { const y = canvas.height / 2 + Math.sin(x * 0.003 + time * speed) * waveHeight + Math.sin(x * 0.005 + time * speed * 1.5) * (waveHeight / 2) + Math.sin(x * 0.002 + time * speed * 0.5) * (waveHeight / 3) + waveOffset - 100; if (x === 0) { ctx.moveTo(x, y); } else { ctx.lineTo(x, y); } } // Create gradient for each wave with animated opacity const waveGradient = ctx.createLinearGradient(0, canvas.height / 2 - 300, 0, canvas.height / 2 + 300); waveGradient.addColorStop(0, `rgba(${color.r}, ${color.g}, ${color.b}, 0)`); waveGradient.addColorStop(0.5, `rgba(${color.r}, ${color.g}, ${color.b}, ${opacityWave})`); waveGradient.addColorStop(1, `rgba(${color.r}, ${color.g}, ${color.b}, 0)`); ctx.strokeStyle = waveGradient; ctx.lineWidth = 4; ctx.stroke(); // Add enhanced glow effect ctx.shadowBlur = 40; ctx.shadowColor = `rgba(${color.r}, ${color.g}, ${color.b}, 0.6)`; ctx.stroke(); ctx.shadowBlur = 0; }); time += 16; requestAnimationFrame(drawAurora); }; drawAurora(); const handleResize = () => { canvas.width = window.innerWidth; canvas.height = window.innerHeight; }; window.addEventListener('resize', handleResize); return () => { window.removeEventListener('resize', handleResize); }; }, []); return (
{/* Glass medallion with frosted effect - made bigger */}
{/* Glowing orb effect */}
{/* Frosted glass background */}
{/* Embossed logo - made bigger */}
Archon
{/* Disconnected Text - Glass style with red glow */}
DISCONNECTED
); }; ================================================ FILE: archon-ui-main/src/components/bug-report/BugReportButton.tsx ================================================ import { Bug, Loader } from "lucide-react"; import { Button } from "../ui/Button"; import { BugReportModal } from "./BugReportModal"; import { useBugReport } from "../../hooks/useBugReport"; interface BugReportButtonProps { error?: Error; variant?: "primary" | "secondary" | "ghost"; size?: "sm" | "md" | "lg"; className?: string; children?: React.ReactNode; } export const BugReportButton: React.FC = ({ error, variant = "ghost", size = "md", className = "", children, }) => { const { isOpen, context, loading, openBugReport, closeBugReport } = useBugReport(); const handleClick = () => { openBugReport(error); }; return ( <> {context && ( )} ); }; ================================================ FILE: archon-ui-main/src/components/bug-report/BugReportModal.tsx ================================================ import { useState } from "react"; import { motion, AnimatePresence } from "framer-motion"; import { Bug, X, Send, Copy, ExternalLink, Loader } from "lucide-react"; import { Button } from "../ui/Button"; import { Input } from "../ui/Input"; import { Card } from "../ui/Card"; import { Select } from "../ui/Select"; import { useToast } from "../../features/shared/hooks/useToast"; import { bugReportService, BugContext, BugReportData, } from "../../services/bugReportService"; import { copyToClipboard } from "../../features/shared/utils/clipboard"; interface BugReportModalProps { isOpen: boolean; onClose: () => void; context: BugContext; } export const BugReportModal: React.FC = ({ isOpen, onClose, context, }) => { const [report, setReport] = useState>({ title: `🐛 ${context.error.name}: ${context.error.message}`, description: "", stepsToReproduce: "", expectedBehavior: "", actualBehavior: context.error.message, severity: "medium", component: "not-sure", }); const [submitting, setSubmitting] = useState(false); const [submitted, setSubmitted] = useState(false); const { showToast } = useToast(); const handleSubmit = async (e: React.FormEvent) => { e.preventDefault(); if (!report.description.trim()) { showToast( "Please provide a description of what you were trying to do", "error", ); return; } setSubmitting(true); try { const bugReportData: BugReportData = { ...report, context, }; const result = await bugReportService.submitBugReport(bugReportData); if (result.success) { setSubmitted(true); if (result.issueNumber) { // Direct API creation (maintainer with token) showToast( `Bug report created! Issue #${result.issueNumber} - maintainers will review it soon.`, "success", 8000, ); if (result.issueUrl) { window.open(result.issueUrl, "_blank"); } } else { // Manual submission (open source user - no token) showToast( "Opening GitHub to submit your bug report...", "success", 5000, ); if (result.issueUrl) { // Force new tab/window opening const newWindow = window.open( result.issueUrl, "_blank", "noopener,noreferrer", ); if (!newWindow) { // Popup blocked - show manual link showToast( "Popup blocked! Please allow popups or click the link in the modal.", "warning", 8000, ); } } } } else { // Fallback: copy to clipboard const formattedReport = bugReportService.formatReportForClipboard(bugReportData); const clipboardResult = await copyToClipboard(formattedReport); if (clipboardResult.success) { showToast( "Failed to create GitHub issue, but bug report was copied to clipboard. Please paste it in a new GitHub issue.", "warning", 10000, ); } else { showToast( "Failed to create GitHub issue and could not copy to clipboard. Please report manually.", "error", 10000, ); } } } catch (error) { console.error("Bug report submission failed:", error); showToast( "Failed to submit bug report. Please try again or report manually.", "error", ); } finally { setSubmitting(false); } }; const handleCopyToClipboard = async () => { const bugReportData: BugReportData = { ...report, context }; const formattedReport = bugReportService.formatReportForClipboard(bugReportData); const result = await copyToClipboard(formattedReport); if (result.success) { showToast("Bug report copied to clipboard", "success"); } else { showToast("Failed to copy to clipboard", "error"); } }; if (!isOpen) return null; return ( e.stopPropagation()} > {/* Header */}

Report Bug

{submitted ? ( /* Success State */

Bug Report Submitted!

Thank you for helping improve Archon. Maintainers will review your report and may comment @claude to trigger automatic analysis and fixes.

) : ( /* Form */
{/* Error Preview */}
{context.error.name}: {context.error.message}
{context.error.stack && (
Stack trace 
                        {context.error.stack}
)}
{/* Bug Title */} setReport((r) => ({ ...r, title: e.target.value })) } placeholder="Brief description of the bug" required /> {/* Severity & Component */}
setReport((r) => ({ ...r, component: e.target.value })) } options={[ { value: "knowledge-base", label: "🔍 Knowledge Base / RAG", }, { value: "mcp-integration", label: "🔗 MCP Integration" }, { value: "projects-tasks", label: "📋 Projects & Tasks" }, { value: "settings", label: "⚙️ Settings & Configuration", }, { value: "ui", label: "🖥️ User Interface" }, { value: "infrastructure", label: "🐳 Docker / Infrastructure", }, { value: "not-sure", label: "❓ Not Sure" }, ]} />
{/* Description */}