initial commit

Author: geraldarthurdavis

.ai/MCPS.md

@@ -0,0 +1,91 @@
+# MCPS.md - Model Context Protocol Tools
+
+**Available Integrations and Capabilities**
+
+## What MCPs Are
+
+Model Context Protocol (MCP) tools extend AI capabilities by providing access to external systems, data sources, and services. Each MCP is a specialized integration that the AI can use during execution.
+
+## Available MCPs (GA-1)
+
+### Design & Collaboration
+
+**Figma**
+- Extract designs and components
+- Analyze design systems
+- Generate code from mockups
+- **Usage:** Attach Figma URLs during Design phase
+
+**Notion**
+- Read documentation
+- Extract requirements
+- Sync specifications
+- **Usage:** Reference Notion docs as context
+
+**Linear**
+- Read issues and projects
+- Understand requirements
+- Track implementation status
+- **Usage:** Link Linear issues for context
+
+### Development Tools
+
+**GitHub**
+- Repository operations (clone, branch, commit, push)
+- PR/issue creation
+- File browsing
+- Code search
+- **Usage:** Automatic integration via VCS connection
+
+**GitLab**
+- Repository operations
+- Merge request creation
+- CI/CD status checking
+- **Usage:** Alternative to GitHub
+
+### Data & Search
+
+**Web Search**
+- Research best practices
+- Find documentation
+- Discover patterns
+- **Usage:** Automatic during Discovery phase
+
+**Firecrawl**
+- Extract content from URLs
+- Parse documentation
+- Process web pages
+- **Usage:** When URLs attached as context
+
+## MCP Configuration
+
+MCPs are initialized during Setup phase of any execution. The system:
+1. Reads available MCPs from user's connections
+2. Registers tools with execution
+3. Makes them available to agents
+
+**File:** `/packages/pipelines/deliverable/src/phases/setup.ts`
+- Agent: `deliverable-pipeline-initialize-mcps-tools-agent`
+
+## Adding New MCPs
+
+To add a new MCP integration:
+
+1. Create MCP package in `/packages/mcp/`
+2. Implement MCP server following protocol
+3. Register in Orbitals > Connects
+4. Add initialization in Setup phase
+5. Document capabilities here in MCPS.md
+
+## MCP Availability
+
+MCPs are available during:
+- **Design Phase:** Read-only (research, documentation)
+- **Develop Phase:** Full access (code operations, data)
+- **Digest Phase:** Read-only (reference for learning capture)
+
+File gates ensure MCPs can only edit allowed files per meta-phase.
+
+---
+
+**This document tracks available tools and integrations.** As new MCPs are added, they're documented here for AI awareness.

.ai/PRODUCT.md

@@ -0,0 +1,92 @@
+# Engi GA-1 Product Guide
+
+This document is the source-of-truth description of the shipping GA-1 experience. Every section maps directly to code in this repository; keep it synchronized whenever source changes.
+
+## Experience Gates
+
+- Guided execution routes tasks through Design → Develop → Digest using `createGuidedPipelineExecution` (`packages/pipelines/deliverable/src/index.ts:115`).
+- Phase handlers live alongside the pipeline: `phases/design.ts`, `phases/index.ts` (Develop SDIVS loop), and `phases/digest.ts`.
+- The current gate is stored in the execution store (`execution.store('guide', ...)`) and exposed to clients through the SSE stream (`uapi/streaming/stream-parser.ts:35` and `uapi/app/executions/components/ExecutionsPageHeader.tsx`).
+
+### Gate Responsibilities
+- **Design**: contextual analysis, attachment digestion, deliverable classification (`packages/pipelines/deliverable/src/phases/design.ts`).
+- **Develop**: SDIVS pipeline with PTRR agents, iteration cap 3 (`packages/pipelines/deliverable/src/index.ts:86-106`).
+- **Digest**: captures work updates, prepares `.ai` diff proposals, and ensures learnings are persisted (`packages/pipelines/deliverable/src/phases/digest.ts`).
+
+## Deliverables Pipeline (Develop Gate)
+
+The Develop gate is the only gate that mutates customer repositories. It is composed of SDIVS phases that delegate to execution-generics patterns (`packages/pipelines/deliverable/src/phases/index.ts`).
+
+### Setup
+- Uses the phase runner declared in `deliverablesPipelineSetupPhaseExecutor` to clone the repository, normalize workspace metadata, and enforce the danger wall before continuing (`setup.ts`).
+- Short-circuit signals issued here propagate to credit refunds (`packages/execution-generics/src/signals/ShortCircuitSignal.ts`).
+
+### Discovery
+- Sequential executor running five research agents (`packages/pipelines/deliverable/src/phases/index.ts:37-47`):
+  - `gather-context`, `understand-requirements`, `research-approach`, `plan-implementation`, `assess-complexity`.
+- Outputs validation criteria consumed later by implementation/validation agents.
+
+### Implementation
+- Determines deliverable type via execution store and selects the correct agent sequence (`packages/pipelines/deliverable/src/phases/index.ts:60-101`).
+- **Code Change**: Divide → parallel Conquer per file → Correct (`implementation:deliverable-pipeline-*` agents).
+- **Code Change Review / Design Document / Design Review**: single PTRR agent per type.
+- File level work emits structured results consumed by validators and shipping agents.
+
+### Validation
+- Parallel validators write issues into `validation/*` stores before the `ready-to-instruct` + `waitIfNeeded` + `ready-to-ship` chain (`packages/pipelines/deliverable/src/phases/index.ts:122-167`).
+- Self-instruction confidence is stored for Digest and UI timers.
+
+### Shipping
+- Always two steps: ship deliverable (VCS interaction) then produce final work summary (`packages/pipelines/deliverable/src/phases/index.ts:172-183`).
+- Uses VCS gated tools so only Develop gate can write to repositories.
+
+### Postprocess & Iterations
+- `factoryIterationPreprocess` loads on-the-fly instructions and attachments per iteration (`packages/pipelines/deliverable/src/index.ts:28-63`).
+- `factoryPostprocess` captures normalized output + artifacts for UI (`packages/pipelines/deliverable/src/index.ts:66-83`).
+
+## Streaming & Work Surfaces
+
+- `enablePipelineStreaming` writes execution state into `execution_events`; SSE polling endpoint streams them to the client (`uapi/app/api/executions/stream/route.ts`).
+- `parseStreamChunk` normalizes events (phase, agent, generation, tool-use, work-update) for UI consumption (`uapi/streaming/stream-parser.ts`).
+- `WorkUpdatePanel` renders agent and iteration updates between the log and instructions (`uapi/components/base/engi/execution/WorkUpdatePanel.tsx`).
+- Completion payloads surface PR/issue metadata, file diffs, duration, and metrics in `ExecutionsCompleteHeaderContent` (`uapi/app/executions/components/ExecutionsCompleteHeaderContent.tsx`).
+
+## User Flow & UI Surfaces
+
+- Unified executables page lives under `/executions`; SSR wrapper keeps `runId` compatibility (`uapi/app/executions/page.tsx`).
+- `ExecutionsPageClient` orchestrates repository selection, template persistence, model selection, attachment intake, and iteration timers (`uapi/app/executions/components/ExecutionsPageClient.tsx:55-200`).
+- Onboarding gate checks for a VCS connection and positive credit balance before allowing execution (`ExecutionsPageClient.tsx:176-197`).
+- SSE state hydrates UI components through `useExecutionState` and `PipelineExecutionLog`.
+
+## API Surface
+
+- `/api/executions` provides unified access; internally delegates to deliverables handlers to avoid regressions (`uapi/app/api/executions/route.ts`, `packages/api/src/routes/deliverables.ts`).
+- `/api/executions/stream` streams execution events with ownership checks and cursor resume support (`uapi/app/api/executions/stream/route.ts:1-200`).
+- `/api/executions/history` rehydrates past runs including guide metadata (`uapi/app/api/executions/history/route.ts`).
+- Stripe webhooks and checkout session endpoints live under `/api/stripe/*` (`uapi/app/api/stripe` routes) and feed the credit ledger.
+
+## Data & Persistence
+
+- Primary tables: `executions`, `execution_events`, `phase_executions` (current GA-1), plus append-only ledgers (`user_credits`, `user_credit_usages`, `generations`). Schema lives in `supabase/migrations/**`.
+- ORM exports typed accessors in `packages/orm/src/index.ts`, aligning with SSOT declared in `packages/orm/src/types/database.ts`.
+- Pipeline iteration metadata (self-instruction, work updates) stored via execution stores; digest guide consumes them to produce `.ai` diffs.
+
+## Credits & Billing
+
+- Credit reservation + settlement handled by `withCreditReservation` around pipeline execution (`packages/api/src/routes/deliverables.ts:152-360`).
+- Escrow tuning constants, ledger writes, and RPC fallback logic reside in `packages/credits/src/index.ts:13-200`.
+- Refunds triggered by short-circuit signals and propagated through credit helpers; partial refunds annotated in execution metadata.
+
+## Digest Responsibilities
+
+- Digest agents collect learnings, propose `.ai` document updates, and ensure follow-up tasks are queued (`packages/pipelines/deliverable/src/phases/digest.ts`).
+- Work-update iteration summaries expose self-instruction confidence and suggested follow-ups for future executions.
+- GA-1 backlog: enforce `.ai` persistence + approval flow before Digest completes (tracked in `internal-docs/GA1.md`).
+
+## Known GA-1 Follow-Ups
+
+- Digest gate approval mechanics and guide history serialization (see `internal-docs/GA1.md`).
+- Finalize structured persistence tables (`deliverables_pipeline_*`) once migrations land.
+- Complete UI polish for WorkUpdatePanel expand/collapse and accessibility.
+
+Keep this document authoritative: when a capability, endpoint, or flow changes in code, update the relevant section with precise paths.

.env

@@ -0,0 +1,13 @@
+# Shared environment variables for Supabase (staging environment - default)
+SUPABASE_URL=https://your-project.supabase.co
+NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
+SUPABASE_ANON_KEY=your-supabase-anon-key
+NEXT_PUBLIC_SUPABASE_ANON_KEY=your-supabase-anon-key
+SUPABASE_SERVICE_ROLE_KEY=your-supabase-service-role-key
+SUPABASE_JWT_SECRET=your-supabase-jwt-secret
+
+# Supabase publishable and secret keys
+SUPABASE_PUBLISHABLE_KEY=sb_publishable_your-key
+SUPABASE_SECRET_KEY=sb_secret_your-key
+
+ENGI_MOCK_EXA=true

.env.local

@@ -0,0 +1,53 @@
+###########################################################################
+# Local UI-feature overrides used while tracking the post-sign-in slowdown.
+# These are placed at the *workspace root* so they win the variable-loading
+# order that Next.js follows ( .env*.local  →  .env.local  →  .env*  →  .env )
+# across every package (uapi, admin, etc.) started by Turborepo.
+###########################################################################
+
+# Marketing toggles ---------------------------------------------------------
+NEXT_PUBLIC_COMING_SOON=false
+NEXT_PUBLIC_SOFT_LAUNCH=false
+NEXT_PUBLIC_CONVERSATION_SECTION=false
+NEXT_PUBLIC_INVISIBLE_INTERFACES_GROUP=true
+NEXT_PUBLIC_DISABLE_USING=false
+NEXT_PUBLIC_LIGHTPAPER_BANNER=false
+
+# High-level UI surfaces ----------------------------------------------------
+NEXT_PUBLIC_NOTIFICATIONS_WIDGET=false
+NEXT_PUBLIC_CONVERSATIONS_WIDGET=false
+
+# Single flag for left sidebar
+NEXT_PUBLIC_SIDEBAR_LEFT=false
+
+# Navigation bar ------------------------------------------------------------
+NEXT_PUBLIC_NAV_BAR=false
+
+# LLM defaults for local development
+ENGI_LLM_PROVIDER=google
+ENGI_LLM_MODEL=gemini-2.5-flash
+ENGI_LOG_FULL_PROMPTS=1
+ENGI_LOG_FULL_PROMPTS_CORRELATION_IDS=
+# Enable per-run log files (deliverables route switches to run-scoped files)
+ENGI_LOG_TO_FILE=1
+# Registry debug (LLM/tool/agent registry config lookups)
+ENGI_DEBUG_REGISTRIES=1
+# Google Generative AI (Gemini)
+GOOGLE_API_KEY=AIzaYourGoogleKey
+GEMINI_API_KEY=AIzaYourGeminiKey
+GOOGLE_GENERATIVE_AI_API_KEY=AIzaYourGenerativeKey
+
+# -------------------------------------------------------------------------
+# Agentic Execution Debugging (added for trace + prompt I/O visibility)
+# -------------------------------------------------------------------------
+LOG_LEVEL=debug
+ENGI_EXECUTION_DEBUG=true
+ENGI_LOG_TRACES=1
+ENGI_LOG_FULL_TRACES=1
+ENGI_WRITE_PROMPT_IO=1
+# Write JSON sidecars for per-step traces
+ENGI_WRITE_STEP_TRACES=1
+# For focused debugging: stop after Plan (omit Try/Refine/Retry)
+ENGI_DEBUG_STOP_AFTER_PLAN=1
+# Optional size guard for full traces (characters). Leave unset for full detail.
+#ENGI_TRACE_MAX_SIZE=5000

.eslintrc.cjs

@@ -0,0 +1,98 @@
+/* Root ESLint config wiring GA-1 prompt hierarchy rules */
+module.exports = {
+  root: true,
+  parser: '@typescript-eslint/parser',
+  parserOptions: {
+    project: './tsconfig.json',
+    tsconfigRootDir: __dirname,
+    sourceType: 'module',
+    ecmaVersion: 2020,
+  },
+  env: { node: true, es6: true, jest: true },
+  plugins: ['@typescript-eslint', 'engi', 'react'],
+  extends: [
+    'eslint:recommended'
+  ],
+  rules: {
+    'engi/no-write-tools-outside-conquer': 'error',
+    'engi/require-prompt-hierarchy': 'error',
+    // Forbid legacy deep-imports into prompts using /src in consumer code.
+    // Canonical pattern is: @engi/prompts/raw_promptparts/*
+    'no-restricted-imports': ['error', {
+      'patterns': [
+        '@engi/prompts/src/raw_promptparts/*'
+      ]
+    }],
+    // Focus on GA-1 custom rules; reduce noise from generic rules
+    'no-unused-vars': 'off',
+    'no-undef': 'off',
+    // Enforce one React component export per file for clarity/maintainability
+    'react/no-multi-comp': ['error', { ignoreStateless: false }],
+  },
+  ignorePatterns: [
+    '**/dist/**',
+    '**/build/**',
+    '**/.turbo/**',
+    '**/.next/**',
+    '**/node_modules/**',
+    '**/*.generated.ts',
+  ],
+  overrides: [
+    // Temporarily allow multiple components in complex route headers
+    {
+      files: [
+        'uapi/app/ai_documents/ai_documentsPageHeader.tsx',
+        'uapi/app/executions/components/ExecutionPageHeader.tsx'
+      ],
+      rules: {
+        'react/no-multi-comp': 'off',
+      }
+    },
+    // Allow multiple components in stories/tests
+    {
+      files: ['**/*.stories.*', '**/*.test.*'],
+      rules: {
+        'react/no-multi-comp': 'off',
+      }
+    },
+    {
+      files: ['**/*.ts', '**/*.tsx'],
+      parserOptions: {
+        project: ['./tsconfig.json'],
+      },
+      rules: {
+        // Disable core rules that are noisy with TS types (handled by TS compiler if needed)
+        'no-unused-vars': 'off',
+        'no-undef': 'off',
+        'no-empty': ['error', { allowEmptyCatch: true }],
+        'no-redeclare': 'off',
+        'no-dupe-class-members': 'off',
+        'no-useless-catch': 'off',
+      }
+    },
+    {
+      files: ['uapi/app/**/*', 'uapi/components/vcs/**/*'],
+      rules: {
+        // Enforce SSOT: forbid importing UI primitives from the vendored folder
+        'no-restricted-imports': ['error', {
+          'patterns': [
+            '@/components/ui/{button,card,input,label,select,tabs,dialog,alert-dialog,dropdown-menu,avatar,switch,textarea,progress,checkbox,popover,collapsible,command,calendar,tooltip,table,badge,alert}'
+          ]
+        }],
+      }
+    },
+    {
+      files: ['**/__tests__/**', '**/*.test.ts', '**/*.test.tsx'],
+      rules: {
+    // Enforce one React component export per file for clarity/maintainability
+    'react/no-multi-comp': ['error', { ignoreStateless: false }],
+        '@typescript-eslint/no-var-requires': 'off',
+        '@typescript-eslint/no-explicit-any': 'off',
+        '@typescript-eslint/no-unused-vars': 'off',
+      },
+    },
+  ],
+  settings: {
+    react: { version: 'detect' }
+  }
+};