vibefast-cli 0.2.4 → 0.3.0

package/2/vf-agent/tasks/shard-doc.md

@@ -0,0 +1,185 @@
+# Document Sharding Task
+
+## Purpose
+
+- Split a large document into multiple smaller documents based on level 2 sections
+- Create a folder structure to organize the sharded documents
+- Maintain all content integrity including code blocks, diagrams, and markdown formatting
+
+## Primary Method: Automatic with markdown-tree
+
+[[LLM: First, check if markdownExploder is set to true in {root}/core-config.yaml. If it is, attempt to run the command: `md-tree explode {input file} {output path}`.
+
+If the command succeeds, inform the user that the document has been sharded successfully and STOP - do not proceed further.
+
+If the command fails (especially with an error indicating the command is not found or not available), inform the user: "The markdownExploder setting is enabled but the md-tree command is not available. Please either:
+
+1. Install @kayvan/markdown-tree-parser globally with: `npm install -g @kayvan/markdown-tree-parser`
+2. Or set markdownExploder to false in {root}/core-config.yaml
+
+**IMPORTANT: STOP HERE - do not proceed with manual sharding until one of the above actions is taken.**"
+
+If markdownExploder is set to false, inform the user: "The markdownExploder setting is currently false. For better performance and reliability, you should:
+
+1. Set markdownExploder to true in {root}/core-config.yaml
+2. Install @kayvan/markdown-tree-parser globally with: `npm install -g @kayvan/markdown-tree-parser`
+
+I will now proceed with the manual sharding process."
+
+Then proceed with the manual method below ONLY if markdownExploder is false.]]
+
+### Installation and Usage
+
+1. **Install globally**:
+
+   ```bash
+   npm install -g @kayvan/markdown-tree-parser
+   ```
+
+2. **Use the explode command**:
+
+   ```bash
+   # For PRD
+   md-tree explode docs/prd.md docs/prd
+
+   # For Architecture
+   md-tree explode docs/architecture.md docs/architecture
+
+   # For any document
+   md-tree explode [source-document] [destination-folder]
+   ```
+
+3. **What it does**:
+   - Automatically splits the document by level 2 sections
+   - Creates properly named files
+   - Adjusts heading levels appropriately
+   - Handles all edge cases with code blocks and special markdown
+
+If the user has @kayvan/markdown-tree-parser installed, use it and skip the manual process below.
+
+---
+
+## Manual Method (if @kayvan/markdown-tree-parser is not available or user indicated manual method)
+
+### Task Instructions
+
+1. Identify Document and Target Location
+
+- Determine which document to shard (user-provided path)
+- Create a new folder under `docs/` with the same name as the document (without extension)
+- Example: `docs/prd.md` → create folder `docs/prd/`
+
+2. Parse and Extract Sections
+
+CRITICAL AEGNT SHARDING RULES:
+
+1. Read the entire document content
+2. Identify all level 2 sections (## headings)
+3. For each level 2 section:
+   - Extract the section heading and ALL content until the next level 2 section
+   - Include all subsections, code blocks, diagrams, lists, tables, etc.
+   - Be extremely careful with:
+     - Fenced code blocks (```) - ensure you capture the full block including closing backticks and account for potential misleading level 2's that are actually part of a fenced section example
+     - Mermaid diagrams - preserve the complete diagram syntax
+     - Nested markdown elements
+     - Multi-line content that might contain ## inside code blocks
+
+CRITICAL: Use proper parsing that understands markdown context. A ## inside a code block is NOT a section header.]]
+
+### 3. Create Individual Files
+
+For each extracted section:
+
+1. **Generate filename**: Convert the section heading to lowercase-dash-case
+   - Remove special characters
+   - Replace spaces with dashes
+   - Example: "## Tech Stack" → `tech-stack.md`
+
+2. **Adjust heading levels**:
+   - The level 2 heading becomes level 1 (# instead of ##) in the sharded new document
+   - All subsection levels decrease by 1:
+
+   ```txt
+     - ### → ##
+     - #### → ###
+     - ##### → ####
+     - etc.
+   ```
+
+3. **Write content**: Save the adjusted content to the new file
+
+### 4. Create Index File
+
+Create an `index.md` file in the sharded folder that:
+
+1. Contains the original level 1 heading and any content before the first level 2 section
+2. Lists all the sharded files with links:
+
+```markdown
+# Original Document Title
+
+[Original introduction content if any]
+
+## Sections
+
+- [Section Name 1](./section-name-1.md)
+- [Section Name 2](./section-name-2.md)
+- [Section Name 3](./section-name-3.md)
+  ...
+```
+
+### 5. Preserve Special Content
+
+1. **Code blocks**: Must capture complete blocks including:
+
+   ```language
+   content
+   ```
+
+2. **Mermaid diagrams**: Preserve complete syntax:
+
+   ```mermaid
+   graph TD
+   ...
+   ```
+
+3. **Tables**: Maintain proper markdown table formatting
+
+4. **Lists**: Preserve indentation and nesting
+
+5. **Inline code**: Preserve backticks
+
+6. **Links and references**: Keep all markdown links intact
+
+7. **Template markup**: If documents contain {{placeholders}} ,preserve exactly
+
+### 6. Validation
+
+After sharding:
+
+1. Verify all sections were extracted
+2. Check that no content was lost
+3. Ensure heading levels were properly adjusted
+4. Confirm all files were created successfully
+
+### 7. Report Results
+
+Provide a summary:
+
+```text
+Document sharded successfully:
+- Source: [original document path]
+- Destination: docs/[folder-name]/
+- Files created: [count]
+- Sections:
+  - section-name-1.md: "Section Title 1"
+  - section-name-2.md: "Section Title 2"
+  ...
+```
+
+## Important Notes
+
+- Never modify the actual content, only adjust heading levels
+- Preserve ALL formatting, including whitespace where significant
+- Handle edge cases like sections with code blocks containing ## symbols
+- Ensure the sharding is reversible (could reconstruct the original from shards)

package/2/vf-agent/tasks/troubleshoot-issue.md

@@ -0,0 +1,65 @@
+==================== START: tasks#troubleshoot-issue ====================
+
+# Task: Interactive Troubleshooter
+
+## Purpose
+
+To guide a user through a structured, step-by-step diagnostic process to identify and solve common problems within the VibeFast starter kit.
+
+## Inputs
+
+- The user's initial description of the problem.
+- Access to the `data#knowledge_base`, especially its "Troubleshooting Common Issues" section.
+- The ability to request specific information from the user (logs, file contents, command outputs).
+
+## Instructions
+
+Execute this diagnostic process sequentially. Do not skip steps.
+
+### 1. Triage the Problem
+
+- **Acknowledge and Confirm:** "Okay, let's troubleshoot this. You're seeing the following problem: `[re-state user's problem description]`."
+- **Categorize the Issue:** Ask the user to categorize their problem to narrow down the possibilities.
+  > "To start, please help me understand the type of issue you're facing. Choose the option that best describes it:
+  >
+  > 1.  **Build/Deployment Error:** The `eas build` command is failing, or you're having issues with CI/CD.
+  > 2.  **Runtime Error:** The app builds and opens, but then it crashes, shows an error screen, or a feature behaves incorrectly.
+  > 3.  **Backend/Data Error:** Data isn't loading from or saving to Convex correctly.
+  > 4.  **UI/Styling Issue:** The app works, but something looks visually wrong.
+  > 5.  **Authentication Issue:** You are having trouble with login, signup, or user sessions.
+  > 6.  **Other:** Something not listed above."
+
+### 2. Gather Specific Information (Based on Triage)
+
+- Based on the user's choice, request the _exact_ information needed for diagnosis.
+- **If Build Error (1):** "Please provide the **full log output** from the failed `eas build` command. The link to the logs on the EAS website is the most helpful."
+- **If Runtime Error (2):** "Please run the app from your terminal (e.g., `pnpm start` and then 'i' or 'a') and **paste the full console log output** that appears when the error occurs."
+- **If Backend Error (3):** "Please go to your Convex dashboard, find the relevant function log that shows an error, and **paste the full log details** here."
+- **If UI Issue (4):** "Please describe what you see versus what you expect. Then, **provide the code for the React Native component file** where the issue is happening."
+- **If Auth Issue (5):** "Please describe the steps you are taking and what happens. Also, please **provide the logs from your terminal** when you attempt to log in."
+
+### 3. Analyze and Form a Hypothesis
+
+- **Analyze Provided Info:** Carefully read the logs or code provided by the user.
+- **Consult the Rulebook:** **Crucially, reference the `data#knowledge_base`**, specifically the "Troubleshooting Common Issues" and other relevant sections.
+- **Form a Hypothesis:** State your hypothesis clearly to the user, referencing the evidence.
+  > "Thank you. I've reviewed the log. The error `[error snippet]` suggests that `[your hypothesis]`. The VibeFast rulebook mentions this can happen when `[reason from rulebook]`."
+
+### 4. Propose a Concrete Solution
+
+- Provide a specific, actionable step for the user to take. Do not be vague.
+- **Bad:** "You should fix your environment variables."
+- **Good:** "Based on my analysis, I recommend you check your `eas.json` file. In the `build.production.env` section, please ensure the `CONVEX_URL` is defined. If it's missing, add it and then start a new build."
+- **Good:** "I believe the issue is in `src/features/chatbot/app/index.tsx`. Please try changing line 42 from `const id = null;` to `const id = conversation._id;` and see if that resolves the crash."
+
+### 5. Verify and Iterate
+
+- **Ask for Outcome:** After providing the solution, ask the user: "Please try that step and let me know if it resolves the issue."
+- **If Fixed:** "Great! I'm glad that worked. Is there anything else I can help you with?" (End task).
+- **If Not Fixed:** "Okay, let's try something else." Return to Step 3, form a new hypothesis based on the new information, and propose a different solution. If you are stuck after three attempts, escalate to the user for a more collaborative debugging session.
+
+==================== END: tasks#troubleshoot-issue ====================
+
+```
+
+```

package/2/vf-agent/tasks/validate-next-story.md

@@ -0,0 +1,47 @@
+# Validate Next Story Task
+
+## Purpose
+
+To comprehensively validate a story draft before implementation, ensuring it is complete and correctly follows the "API-First" hybrid slicing model.
+
+## SEQUENTIAL Task Execution
+
+### 1. Load Context and Inputs
+
+- Load the story file to be validated.
+- Load the sharded architecture documents.
+- Load the VibeFast Knowledge Core via `vf-agent/data/knowledge_base/master-rulebook.md`.
+
+### 2. Completeness & Story Type Check
+
+- Verify all required sections of the story are present and filled.
+- **CRITICAL:** Identify the `Story Type`. All subsequent checks will be performed against this type.
+- **If Frontend Story:** Verify that it references a corresponding Backend story and that the backend story is marked as "Done" or "Review". A frontend story cannot be implemented before its API contract is complete.
+
+### 3. Focused Architecture & Rulebook Alignment
+
+- **Cross-reference Dev Notes:** Read the "Dev Notes" section.
+- **Validate Focused Context:** Ensure the technical guidance is appropriate for the story type.
+  - **Backend Story:** Does it focus only on schema, Convex functions, and backend tests?
+  - **Frontend Story:** Does it focus only on components, hooks, and frontend tests?
+- Flag any "context leakage" (e.g., detailed UI rules in a backend story).
+
+### 4. Task & Acceptance Criteria Cohesion
+
+- Verify that the tasks align with the story type and cover all acceptance criteria.
+
+### 5. Generate Validation Report
+
+Provide a structured validation report to the user:
+
+**Story Validation Report for: {Story Number & Title}**
+**Story Type:** [Backend (API Contract) / Frontend (API Consumer)]
+
+- **Template Compliance:** [✓/✗]
+- **Workflow Compliance:** [✓/✗] (Comments on whether the story correctly follows the BE/FE separation)
+- **Focused Context:** [✓/✗] (Comments on any context leakage)
+- **Task/AC Coverage:** [✓/✗]
+- **Implementation Readiness:** [GO / NO-GO]
+
+**Summary:**
+[Provide a 1-2 sentence summary. If NO-GO, state the primary reason, e.g., "NO-GO: This frontend story's corresponding backend story (1.1) is not yet complete."]

package/2/vf-agent/templates/brainstorming-output-tmpl.yaml

@@ -0,0 +1,156 @@
+template:
+  id: brainstorming-output-template-v2
+  name: Brainstorming Session Results
+  version: 2.0
+  output:
+    format: markdown
+    filename: docs/brainstorming-session-results.md
+    title: 'Brainstorming Session Results'
+
+workflow:
+  mode: non-interactive
+
+sections:
+  - id: header
+    content: |
+      **Session Date:** {{date}}
+      **Facilitator:** {{agent_role}} {{agent_name}}
+      **Participant:** {{user_name}}
+
+  - id: executive-summary
+    title: Executive Summary
+    sections:
+      - id: summary-details
+        template: |
+          **Topic:** {{session_topic}}
+
+          **Session Goals:** {{stated_goals}}
+
+          **Techniques Used:** {{techniques_list}}
+
+          **Total Ideas Generated:** {{total_ideas}}
+      - id: key-themes
+        title: 'Key Themes Identified:'
+        type: bullet-list
+        template: '- {{theme}}'
+
+  - id: technique-sessions
+    title: Technique Sessions
+    repeatable: true
+    sections:
+      - id: technique
+        title: '{{technique_name}} - {{duration}}'
+        sections:
+          - id: description
+            template: '**Description:** {{technique_description}}'
+          - id: ideas-generated
+            title: 'Ideas Generated:'
+            type: numbered-list
+            template: '{{idea}}'
+          - id: insights
+            title: 'Insights Discovered:'
+            type: bullet-list
+            template: '- {{insight}}'
+          - id: connections
+            title: 'Notable Connections:'
+            type: bullet-list
+            template: '- {{connection}}'
+
+  - id: idea-categorization
+    title: Idea Categorization
+    sections:
+      - id: immediate-opportunities
+        title: Immediate Opportunities
+        content: '*Ideas ready to implement now*'
+        repeatable: true
+        type: numbered-list
+        template: |
+          **{{idea_name}}**
+          - Description: {{description}}
+          - Why immediate: {{rationale}}
+          - Resources needed: {{requirements}}
+      - id: future-innovations
+        title: Future Innovations
+        content: '*Ideas requiring development/research*'
+        repeatable: true
+        type: numbered-list
+        template: |
+          **{{idea_name}}**
+          - Description: {{description}}
+          - Development needed: {{development_needed}}
+          - Timeline estimate: {{timeline}}
+      - id: moonshots
+        title: Moonshots
+        content: '*Ambitious, transformative concepts*'
+        repeatable: true
+        type: numbered-list
+        template: |
+          **{{idea_name}}**
+          - Description: {{description}}
+          - Transformative potential: {{potential}}
+          - Challenges to overcome: {{challenges}}
+      - id: insights-learnings
+        title: Insights & Learnings
+        content: '*Key realizations from the session*'
+        type: bullet-list
+        template: '- {{insight}}: {{description_and_implications}}'
+
+  - id: action-planning
+    title: Action Planning
+    sections:
+      - id: top-priorities
+        title: Top 3 Priority Ideas
+        sections:
+          - id: priority-1
+            title: '#1 Priority: {{idea_name}}'
+            template: |
+              - Rationale: {{rationale}}
+              - Next steps: {{next_steps}}
+              - Resources needed: {{resources}}
+              - Timeline: {{timeline}}
+          - id: priority-2
+            title: '#2 Priority: {{idea_name}}'
+            template: |
+              - Rationale: {{rationale}}
+              - Next steps: {{next_steps}}
+              - Resources needed: {{resources}}
+              - Timeline: {{timeline}}
+          - id: priority-3
+            title: '#3 Priority: {{idea_name}}'
+            template: |
+              - Rationale: {{rationale}}
+              - Next steps: {{next_steps}}
+              - Resources needed: {{resources}}
+              - Timeline: {{timeline}}
+
+  - id: reflection-followup
+    title: Reflection & Follow-up
+    sections:
+      - id: what-worked
+        title: What Worked Well
+        type: bullet-list
+        template: '- {{aspect}}'
+      - id: areas-exploration
+        title: Areas for Further Exploration
+        type: bullet-list
+        template: '- {{area}}: {{reason}}'
+      - id: recommended-techniques
+        title: Recommended Follow-up Techniques
+        type: bullet-list
+        template: '- {{technique}}: {{reason}}'
+      - id: questions-emerged
+        title: Questions That Emerged
+        type: bullet-list
+        template: '- {{question}}'
+      - id: next-session
+        title: Next Session Planning
+        template: |
+          - **Suggested topics:** {{followup_topics}}
+          - **Recommended timeframe:** {{timeframe}}
+          - **Preparation needed:** {{preparation}}
+
+  - id: footer
+    content: |
+      ---
+
+      *Session facilitated using the Vibefast-METHOD brainstorming framework*

package/2/vf-agent/templates/brownfield-architecture-tmpl.yaml

@@ -0,0 +1,111 @@
+template:
+  id: architecture-template-v1
+  name: VibeFast Enhancement Architecture
+  version: 1.0
+  output:
+    format: markdown
+    filename: docs/architecture.md
+    title: '{{project_name}} VibeFast Enhancement Architecture'
+
+workflow:
+  mode: interactive
+  elicitation: advanced-elicitation
+
+sections:
+  - id: introduction
+    title: Introduction
+    instruction: |
+      CRITICAL: Your primary context for this task is the VibeFast Knowledge Core. You MUST start by loading `vf-agent/data/knowledge_base/master-rulebook.md`. All architectural decisions must align with the principles and rules linked within that document.
+    elicit: true
+    sections:
+      - id: intro-content
+        content: |
+          This document outlines the architectural approach for enhancing {{project_name}} with {{enhancement_description}}. Its primary goal is to serve as the guiding architectural blueprint for AI-driven development of new features while ensuring seamless integration with the existing VibeFast system. It supplements the existing project architecture by defining how new components will integrate.
+      - id: existing-project-analysis
+        title: Existing Project Analysis
+        instruction: |
+          Analyze the existing VibeFast project structure. Your analysis must confirm the location and patterns of:
+          1. The Convex backend in `convex/`.
+          2. The React Native frontend in `src/`.
+          3. The core UI components in `src/components/ui/`.
+          4. The core service adapters in `src/core/`.
+          CRITICAL: After your analysis, explicitly validate your findings: "Based on my analysis of your project, I've identified the core VibeFast structure. Please confirm these observations are accurate before I proceed."
+        elicit: true
+      - id: changelog
+        title: Change Log
+        type: table
+        columns: [Change, Date, Version, Description, Author]
+
+  - id: application-feature-decomposition
+    title: Application Feature Decomposition
+    instruction: |
+      CRITICAL: Based on the PRD, decompose the high-level application concept (e.g., "Calorie Tracker") into a set of smaller, logical, feature-sliced modules. Do NOT plan the entire application as a single feature. List the new feature modules that will be created within `src/features/`. For example: `dashboard`, `food-logging`, `user-profile`, `workout-tracking`, etc.
+    elicit: true
+
+  - id: existing-feature-reuse
+    title: Existing Feature Reuse Strategy
+    instruction: |
+      CRITICAL: Analyze the existing VibeFast feature set by consulting `vf-agent/data/knowledge_base/starter-docs/feature-reference-index.md`. Document which of these existing features will be extended or reconfigured to meet the new PRD requirements. This is a mandatory step to avoid re-implementing existing functionality.
+    elicit: true
+
+  - id: tech-stack-alignment
+    title: Tech Stack Alignment
+    instruction: |
+      All technologies MUST align with `vf-agent/data/knowledge_base/starter-docs/tech-stack.md`. No new dependencies should be introduced without explicit user approval and strong justification. Document any required additions here.
+    elicit: true
+    type: table
+    columns: [Technology, Version, Rationale, Integration Method]
+
+  - id: convex-backend-architecture
+    title: Convex Backend Architecture
+    instruction: 'CRITICAL: Load and adhere to the rules in `vf-agent/data/knowledge_base/backend/`. Specifically reference `convex-main.md`, `convex-database.md`, and `convex-advanced.md` when making decisions.'
+    elicit: true
+    sections:
+      - id: schema-changes
+        title: Schema Changes (convex/schema.ts)
+        instruction: 'Define any new tables or modifications. Ensure all new queries are supported by indexes as defined in `backend/convex-database.md`.'
+      - id: new-functions
+        title: New Server Functions (convex/*.ts)
+        instruction: 'List all new queries, mutations, and actions. Every function MUST include validators and use the new function syntax as defined in `backend/convex-main.md`. Adhere to the `camelCase` file naming convention.'
+      - id: http-endpoints
+        title: HTTP Endpoint Changes (convex/http.ts)
+        instruction: 'Define any changes to HTTP actions, including authentication checks as described in `backend/convex-advanced.md`.'
+
+  - id: frontend-architecture
+    title: React Native Frontend Architecture
+    instruction: 'CRITICAL: Load and adhere to the rules in `vf-agent/data/knowledge_base/frontend/`. Specifically reference `react-native-main.md`, `ui-and-styling.md`, and `image-handling.md`.'
+    elicit: true
+    sections:
+      - id: new-components
+        title: New Components (src/features/ and src/components/)
+        instruction: 'Describe new components. They MUST be built using base components and styled with NativeWind as defined in `frontend/ui-and-styling.md`. Adhere to the `kebab-case` file naming convention.'
+      - id: new-screens
+        title: New Screens (src/app/)
+        instruction: 'Define new screens and their routes, following the Expo Router file-based structure (`(tabs)` vs `(routes)`).'
+      - id: state-management
+        title: State Management Strategy
+        instruction: 'Specify which state management tool to use for each part of the new feature, following the guidelines in `frontend/react-native-main.md`.'
+      - id: service-integration
+        title: Core Service Integration
+        instruction: 'Describe how the new feature will use or extend services from `src/core/` (e.g., logging, caching, payments).'
+
+  - id: data-flow-and-workflows
+    title: Data Flow and Core Workflows
+    type: mermaid
+    mermaid_type: sequence
+    instruction: |
+      Illustrate the key workflows for this new feature using sequence diagrams. The diagrams MUST show the interaction between React Native components, Convex hooks, and the Convex backend functions.
+    elicit: true
+
+  - id: testing-strategy-update
+    title: Testing Strategy
+    instruction: |
+      CRITICAL: Load and adhere to the rules in `vf-agent/data/knowledge_base/testing/`. Define the testing approach for this new feature, specifying unit tests for both backend (`backend-testing.md`) and frontend (`frontend-testing.md`).
+    elicit: true
+    sections:
+      - id: backend-tests
+        title: Backend Testing
+      - id: frontend-tests
+        title: Frontend Testing
+      - id: e2e-tests
+        title: End-to-End Testing