vibefast-cli 0.2.4 → 0.3.0

package/2/vf-agent/data/knowledge_base/starter-docs/unified-project-structure.md

@@ -0,0 +1,98 @@
+# Unified Project Structure (Monorepo)
+
+## Overview
+
+VibeFast now lives inside a pnpm + Turborepo monorepo. The Expo client, Convex backend, shared packages, and documentation all coexist under a single root so code can be shared safely between apps. The legacy `vibefast-pro` project remains as a reference; all new work happens in the monorepo.
+
+```
+├─ apps/                # End-user applications
+│  └─ native/           # Expo project (primary mobile app)
+├─ packages/            # Shared libraries and backend services
+│  └─ backend/          # Convex backend package
+├─ docs/                # Living developer documentation (native-focused)
+├─ vf-agent/            # Knowledge base for AI/agent workflows
+├─ turbo.json           # Turborepo task graph
+├─ pnpm-workspace.yaml  # Workspace definitions
+└─ package.json         # Root scripts and toolchain
+```
+
+## Root Directory
+
+| Path                            | Purpose                                                                                          |
+| ------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `package.json`                  | Root scripts (`dev:native`, `dev:server`, lint/type-check pipelines) and shared devDependencies. |
+| `pnpm-workspace.yaml`           | Declares `apps/*` and `packages/*` workspaces.                                                   |
+| `turbo.json`                    | Task orchestration for build, lint, test, and dev commands.                                      |
+| `docs/`                         | Human-authored guides for setup and day-to-day workflows.                                        |
+| `vf-agent/data/knowledge_base/` | This knowledge base—kept in sync with the active architecture.                                   |
+| `apps/`                         | Houses application workspaces (`native` today; room for `web` in the future).                    |
+| `packages/`                     | Backend and reusable packages shared across apps.                                                |
+
+## Expo Application (`apps/native`)
+
+The Expo app keeps the existing feature-sliced architecture from `vibefast-pro`, but it now resides under `apps/native/`.
+
+```
+apps/native/
+├─ assets/              # Fonts, images, Lottie animations, static data
+├─ src/
+│  ├─ app/              # Expo Router routes and layouts
+│  ├─ components/       # Design-system primitives + advanced UI
+│  ├─ core/             # Cross-cutting services (auth, analytics, logging, payments…)
+│  ├─ features/         # Product features (chatbot, analyzer, quick-actions, etc.)
+│  ├─ lib/              # Shared hooks, utilities, i18n, Convex client
+│  ├─ providers/        # Top-level provider composition
+│  ├─ translations/     # i18n resources
+│  └─ types/            # Shared TypeScript types
+├─ scripts/             # Expo/EAS scripting utilities
+├─ package.json         # App-specific dependencies and scripts
+├─ app.config.ts        # Expo runtime configuration (reads env files)
+├─ babel.config.js      # Babel setup with module resolver aliases
+└─ metro.config.js      # Metro configured for monorepo resolution
+```
+
+### Path & Import Conventions
+
+- All guides reference files using the Expo workspace root, e.g. `apps/native/src/features/...`.
+- TypeScript and Metro expose the alias `@/` that maps to `apps/native/src/`. Prefer `import { Button } from '@/components/ui'` in code.
+- Environment files live beside the app (`apps/native/.env.development`, etc.) and are read by `env.js`/`app.config.ts`.
+- Metro uses a custom `resolveRequest` helper (see `apps/native/metro.config.js`) so workspace packages like `@vibefast/backend` resolve correctly; keep new workspace packages in sync with that resolver.
+- Babel’s module-resolver plugin also defines `@assets` → `./assets` so asset imports work in Metro; add new aliases in both Babel and TypeScript if needed.
+
+## Convex Backend (`packages/backend`)
+
+The backend runs as a workspace package named `@vibefast/backend`.
+
+```
+packages/backend/
+├─ convex/              # Convex schema, functions, actions, HTTP endpoints
+│  ├─ _generated/       # Auto-generated API & data model types (regenerated via Convex CLI)
+│  ├─ auth*.ts          # @convex-dev/auth configuration and helpers
+│  ├─ lib/              # Shared backend utilities (AI adapters, telemetry, rate limiting)
+│  └─ *.ts              # Domain modules (chatbot, payments, analyzer, etc.)
+├─ package.json         # Workspace metadata and Convex scripts
+└─ index.ts             # Entry point for consumers that need server helpers
+```
+
+### Backend Notes
+
+- Convex CLI commands run from `packages/backend` (or via root scripts like `pnpm dev:server`).
+- Environment variables must be synced to the Convex cloud deployment (`npx convex env set ...`).
+- Frontend code imports generated types via `@vibefast/backend/_generated/*`.
+- The backend package exposes explicit subpath exports in `packages/backend/package.json`; add new exports if you introduce additional entry points so Metro can resolve them.
+
+## Additional Packages
+
+`packages/ui/` and other shared libraries can be introduced as migrations progress. Metro’s `extraNodeModules` and the root `tsconfig.json` already support workspace imports—add new packages there when they come online.
+
+## Knowledge Base (`vf-agent/data/knowledge_base`)
+
+This folder (where you are reading) mirrors the active structure and standards. Any change to layout, tooling, or feature ownership must be reflected here so AI agents and developers share the same mental model.
+
+## Key Differences from `vibefast-pro`
+
+- **Monorepo-first:** Multiple apps and packages share one lockfile and Turbo task graph.
+- **Path updates:** Physical paths now start with `apps/native/...` and `packages/backend/...` instead of root-level `src/` and `convex/`.
+- **Documentation split:** High-level runbooks live in `docs/`; canonical architectural detail stays in this knowledge base.
+
+When updating documentation or planning migrations, always reference this structure. Any new feature or package should document its location relative to these directories.

package/2/vf-agent/data/knowledge_base/testing/backend-testing.md

@@ -0,0 +1,54 @@
+# Backend Testing Patterns (Vitest)
+
+## 1. Test Runner and Syntax
+
+- All backend tests in the `packages/backend/convex/` directory **MUST** be written using **Vitest** syntax (`describe`, `test`, `expect`).
+- Tests are run via the designated script in `package.json` (e.g., `pnpm test:backend`).
+
+## 2. The `convexTest` Helper
+
+- Use the `convexTest` utility from `convex/testing` to create an isolated test environment for each test suite. This provides a mock database that respects your `packages/backend/convex/schema.ts`.
+
+  ```ts
+  import { convexTest } from 'convex/testing';
+  import { test } from 'vitest';
+  import schema from './schema';
+
+  test('a test with the database', async () => {
+    const t = convexTest(schema);
+    // ...
+  });
+  ```
+
+## 3\. Executing Functions
+
+- Within a test, execute your Convex functions using the test environment object `t`.
+
+- This correctly simulates the context (`ctx`) that your functions expect.
+
+  ```typescript
+  import { api } from './_generated/api';
+
+  // Inside a test
+  const result = await t.query(api.myModule.myQuery, { arg1: 'value' });
+  await t.mutation(api.myModule.myMutation, { arg1: 'value' });
+  ```
+
+## 4\. Mocking Dependencies
+
+- For `actions` that call external services (e.g., OpenAI), use `vi.mock()` from Vitest to mock the API client library.
+
+- This allows you to test your action's logic without making actual network requests.
+
+  ```typescript
+  import { vi } from 'vitest';
+  import OpenAI from 'openai';
+
+  // Mock the entire module
+  vi.mock('openai');
+
+  // Inside a test, you can control the mock's behavior
+  vi.mocked(OpenAI.prototype.chat.completions.create).mockResolvedValue({
+    // ... mock response
+  });
+  ```

package/2/vf-agent/data/knowledge_base/testing/frontend-testing.md

@@ -0,0 +1,71 @@
+# Frontend Testing Patterns (Jest & RNTL)
+
+## Rule 1: Mock Hoisting & File Structure
+
+ALL `jest.mock('module-path', ...)` calls **MUST** be at the very top of your test file, before any `import` statements. This is required for Jest's hoisting mechanism to work correctly.
+
+```typescript
+// 1. Mocks are ALWAYS first.
+jest.mock('expo-router');
+jest.mock('convex/react');
+
+// 2. Imports come after mocks.
+import { render, screen, act } from '@testing-library/react-native';
+import MyComponent from './MyComponent';
+
+// 3. Test code follows.
+```
+
+## Rule 2: Dependency Analysis & Mocking Strategy
+
+Before writing a test, analyze the component's imports and mock all external dependencies to isolate the component.
+
+- **Navigation:** Mock `expo-router` to control `useRouter` and `useLocalSearchParams`.
+- **Convex Hooks:** Mock `convex/react` to provide controlled data to `useQuery` and mock the functions returned by `useMutation` and `useAction` (frontend code still imports from `convex/react`).
+- **Expo/React Native APIs:** Mock specific APIs like `expo-image-picker` or `react-native`'s `Alert`.
+- **Custom UI Components:** Mock complex UI components from `@/components/ui` if they interfere with the test, but it is often better to render them if they are simple.
+
+## Rule 3: `act` and `waitFor` for Async Operations
+
+All interactions that cause a state update in React **MUST** be wrapped in `act`. For asserting the results of an async update, you **MUST** use `waitFor`.
+````ts
+// ✅ CORRECT
+import { fireEvent, waitFor, act } from '@testing-library/react-native';
+
+    test('updates text after button press', async () => {
+    render(<MyComponent />);
+    const button = screen.getByText('Press Me');
+
+    // Wrap the event that causes the state update in act
+    act(() => {
+        fireEvent.press(button);
+    });
+
+    // Use waitFor to assert the result of the async update
+    await waitFor(() => {
+        expect(screen.getByText('Updated!')).toBeOnTheScreen();
+    });
+    });
+    ````
+
+## Rule 4: Type-Accurate Data Mocks
+
+When mocking data, especially from Convex, the mock object **MUST** match the TypeScript type definition exactly.
+
+- Refer to `@vibefast/backend/_generated/dataModel.d.ts` for `Doc<"tableName">` and `Id<"tableName">` types.
+- Include system fields like `_id` and `_creationTime`.
+- Use type casting for `Id` types in mocks: `_id: "mockId" as Id<"users">`.
+
+## Rule 5: Debugging Protocol (Three-Strikes)
+
+If a test fails and the reason is not obvious:
+
+1.  **Strike 1 (Check Basics):** Read the error message carefully. Check for typos in `testID`s and ensure mocks are being called.
+2.  **Strike 2 (Verify Mocks):** Add `console.log` inside your mock implementations to see if they are being executed and what they are returning. Ensure the mock's return value perfectly matches what the component expects.
+3.  **Strike 3 (Isolate):** Comment out parts of your test to isolate the single interaction that is failing. Simplify the test case to the absolute minimum required to reproduce the error.
+
+If the issue persists after three attempts, **STOP**, document the problem, and ask for human guidance.
+
+```
+
+```

package/2/vf-agent/data/knowledge_base/testing/testing-strategy.md

@@ -0,0 +1,31 @@
+# Overall Testing Strategy
+
+This project follows a balanced testing pyramid approach to ensure code quality, reliability, and maintainability.
+
+## 1. Backend Testing (Vitest)
+
+- All Convex functions (queries, mutations, and actions) that contain business logic **MUST** be covered by unit tests.
+- Tests are written using **Vitest** and run via the project's designated backend test script.
+- The `convexTest` utility is used to provide a mock database environment.
+- Focus on testing logic, data transformations, and authorization rules.
+
+## 2. Frontend Unit & Integration Testing (Jest & RNTL)
+
+- **Unit Tests:** Utilities, complex hooks, and core services should have unit tests.
+- **Integration Tests:** Most component tests will be integration tests that verify the component renders correctly and responds to user interactions.
+- All frontend tests are written using **Jest** and **React Native Testing Library (RNTL)**.
+- Focus on testing what the user sees and interacts with, not implementation details. Assert on the rendered output and accessibility props.
+
+## 3. End-to-End (E2E) Testing (Maestro)
+
+- Critical user flows (e.g., authentication, core feature usage) will be covered by E2E tests written for **Maestro**.
+- To support E2E testing, all key interactive elements and screens **MUST** have a `testID` prop.
+
+## 4. General Principles
+
+- **Co-location:** Test files should be co-located with the source code they are testing (e.g., `my-component.test.tsx` next to `my-component.tsx`).
+- **Coverage:** Aim for high coverage of critical business logic. Do not waste time testing simple presentational components that have no logic.
+
+```
+
+```

package/2/vf-agent/tasks/advanced-elicitation.md

@@ -0,0 +1,117 @@
+# Advanced Elicitation Task
+
+## Purpose
+
+- Provide optional reflective and brainstorming actions to enhance content quality
+- Enable deeper exploration of ideas through structured elicitation techniques
+- Support iterative refinement through multiple analytical perspectives
+- Usable during template-driven document creation or any chat conversation
+
+## Usage Scenarios
+
+### Scenario 1: Template Document Creation
+
+After outputting a section during document creation:
+
+1. **Section Review**: Ask user to review the drafted section
+2. **Offer Elicitation**: Present 9 carefully selected elicitation methods
+3. **Simple Selection**: User types a number (0-8) to engage method, or 9 to proceed
+4. **Execute & Loop**: Apply selected method, then re-offer choices until user proceeds
+
+### Scenario 2: General Chat Elicitation
+
+User can request advanced elicitation on any agent output:
+
+- User says "do advanced elicitation" or similar
+- Agent selects 9 relevant methods for the context
+- Same simple 0-9 selection process
+
+## Task Instructions
+
+### 1. Intelligent Method Selection
+
+**Context Analysis**: Before presenting options, analyze:
+
+- **Content Type**: Technical specs, user stories, architecture, requirements, etc.
+- **Complexity Level**: Simple, moderate, or complex content
+- **Stakeholder Needs**: Who will use this information
+- **Risk Level**: High-impact decisions vs routine items
+- **Creative Potential**: Opportunities for innovation or alternatives
+
+**Method Selection Strategy**:
+
+1. **Always Include Core Methods** (choose 3-4):
+   - Expand or Contract for Audience
+   - Critique and Refine
+   - Identify Potential Risks
+   - Assess Alignment with Goals
+
+2. **Context-Specific Methods** (choose 4-5):
+   - **Technical Content**: Tree of Thoughts, ReWOO, Meta-Prompting
+   - **User-Facing Content**: Agile Team Perspective, Stakeholder Roundtable
+   - **Creative Content**: Innovation Tournament, Escape Room Challenge
+   - **Strategic Content**: Red Team vs Blue Team, Hindsight Reflection
+
+3. **Always Include**: "Proceed / No Further Actions" as option 9
+
+### 2. Section Context and Review
+
+When invoked after outputting a section:
+
+1. **Provide Context Summary**: Give a brief 1-2 sentence summary of what the user should look for in the section just presented
+
+2. **Explain Visual Elements**: If the section contains diagrams, explain them briefly before offering elicitation options
+
+3. **Clarify Scope Options**: If the section contains multiple distinct items, inform the user they can apply elicitation actions to:
+   - The entire section as a whole
+   - Individual items within the section (specify which item when selecting an action)
+
+### 3. Present Elicitation Options
+
+**Review Request Process:**
+
+- Ask the user to review the drafted section
+- In the SAME message, inform them they can suggest direct changes OR select an elicitation method
+- Present 9 intelligently selected methods (0-8) plus "Proceed" (9)
+- Keep descriptions short - just the method name
+- Await simple numeric selection
+
+**Action List Presentation Format:**
+
+```text
+**Advanced Elicitation Options**
+Choose a number (0-8) or 9 to proceed:
+
+0. [Method Name]
+1. [Method Name]
+2. [Method Name]
+3. [Method Name]
+4. [Method Name]
+5. [Method Name]
+6. [Method Name]
+7. [Method Name]
+8. [Method Name]
+9. Proceed / No Further Actions
+```
+
+**Response Handling:**
+
+- **Numbers 0-8**: Execute the selected method, then re-offer the choice
+- **Number 9**: Proceed to next section or continue conversation
+- **Direct Feedback**: Apply user's suggested changes and continue
+
+### 4. Method Execution Framework
+
+**Execution Process:**
+
+1. **Retrieve Method**: Access the specific elicitation method from the elicitation-methods data file
+2. **Apply Context**: Execute the method from your current role's perspective
+3. **Provide Results**: Deliver insights, critiques, or alternatives relevant to the content
+4. **Re-offer Choice**: Present the same 9 options again until user selects 9 or gives direct feedback
+
+**Execution Guidelines:**
+
+- **Be Concise**: Focus on actionable insights, not lengthy explanations
+- **Stay Relevant**: Tie all elicitation back to the specific content being analyzed
+- **Identify Personas**: For multi-persona methods, clearly identify which viewpoint is speaking
+- **Maintain Flow**: Keep the process moving efficiently

package/2/vf-agent/tasks/brownfield-create-epic.md

@@ -0,0 +1,160 @@
+# Create Brownfield Epic Task
+
+## Purpose
+
+Create a single epic for smaller brownfield enhancements that don't require the full PRD and Architecture documentation process. This task is for isolated features or modifications that can be completed within a focused scope.
+
+## When to Use This Task
+
+**Use this task when:**
+
+- The enhancement can be completed in 1-3 stories
+- No significant architectural changes are required
+- The enhancement follows existing project patterns
+- Integration complexity is minimal
+- Risk to existing system is low
+
+**Use the full brownfield PRD/Architecture process when:**
+
+- The enhancement requires multiple coordinated stories
+- Architectural planning is needed
+- Significant integration work is required
+- Risk assessment and mitigation planning is necessary
+
+## Instructions
+
+### 1. Project Analysis (Required)
+
+Before creating the epic, gather essential information about the existing project:
+
+**Existing Project Context:**
+
+- [ ] Project purpose and current functionality understood
+- [ ] Existing technology stack identified
+- [ ] Current architecture patterns noted
+- [ ] Integration points with existing system identified
+
+**Enhancement Scope:**
+
+- [ ] Enhancement clearly defined and scoped
+- [ ] Impact on existing functionality assessed
+- [ ] Required integration points identified
+- [ ] Success criteria established
+
+### 2. Epic Creation
+
+Create a focused epic following this structure:
+
+#### Epic Title
+
+{{Enhancement Name}} - Brownfield Enhancement
+
+#### Epic Goal
+
+{{1-2 sentences describing what the epic will accomplish and why it adds value}}
+
+#### Epic Description
+
+**Existing System Context:**
+
+- Current relevant functionality: {{brief description}}
+- Technology stack: {{relevant existing technologies}}
+- Integration points: {{where new work connects to existing system}}
+
+**Enhancement Details:**
+
+- What's being added/changed: {{clear description}}
+- How it integrates: {{integration approach}}
+- Success criteria: {{measurable outcomes}}
+
+#### Stories
+
+List 1-3 focused stories that complete the epic:
+
+1. **Story 1:** {{Story title and brief description}}
+2. **Story 2:** {{Story title and brief description}}
+3. **Story 3:** {{Story title and brief description}}
+
+#### Compatibility Requirements
+
+- [ ] Existing APIs remain unchanged
+- [ ] Database schema changes are backward compatible
+- [ ] UI changes follow existing patterns
+- [ ] Performance impact is minimal
+
+#### Risk Mitigation
+
+- **Primary Risk:** {{main risk to existing system}}
+- **Mitigation:** {{how risk will be addressed}}
+- **Rollback Plan:** {{how to undo changes if needed}}
+
+#### Definition of Done
+
+- [ ] All stories completed with acceptance criteria met
+- [ ] Existing functionality verified through testing
+- [ ] Integration points working correctly
+- [ ] Documentation updated appropriately
+- [ ] No regression in existing features
+
+### 3. Validation Checklist
+
+Before finalizing the epic, ensure:
+
+**Scope Validation:**
+
+- [ ] Epic can be completed in 1-3 stories maximum
+- [ ] No architectural documentation is required
+- [ ] Enhancement follows existing patterns
+- [ ] Integration complexity is manageable
+
+**Risk Assessment:**
+
+- [ ] Risk to existing system is low
+- [ ] Rollback plan is feasible
+- [ ] Testing approach covers existing functionality
+- [ ] Team has sufficient knowledge of integration points
+
+**Completeness Check:**
+
+- [ ] Epic goal is clear and achievable
+- [ ] Stories are properly scoped
+- [ ] Success criteria are measurable
+- [ ] Dependencies are identified
+
+### 4. Handoff to Story Manager
+
+Once the epic is validated, provide this handoff to the Story Manager:
+
+---
+
+**Story Manager Handoff:**
+
+"Please develop detailed user stories for this brownfield epic. Key considerations:
+
+- This is an enhancement to an existing system running {{technology stack}}
+- Integration points: {{list key integration points}}
+- Existing patterns to follow: {{relevant existing patterns}}
+- Critical compatibility requirements: {{key requirements}}
+- Each story must include verification that existing functionality remains intact
+
+The epic should maintain system integrity while delivering {{epic goal}}."
+
+---
+
+## Success Criteria
+
+The epic creation is successful when:
+
+1. Enhancement scope is clearly defined and appropriately sized
+2. Integration approach respects existing system architecture
+3. Risk to existing functionality is minimized
+4. Stories are logically sequenced for safe implementation
+5. Compatibility requirements are clearly specified
+6. Rollback plan is feasible and documented
+
+## Important Notes
+
+- This task is specifically for SMALL brownfield enhancements
+- If the scope grows beyond 3 stories, consider the full brownfield PRD process
+- Always prioritize existing system integrity over new functionality
+- When in doubt about scope or complexity, escalate to full brownfield planning