Your First Project - Step by Step

Last updated 7 months ago

MoodTracker Project - Following Best Practices

A step-by-step guide that must be followed in exact order

🛑 READ THIS FIRST

This guide has THREE CRITICAL PREPARATION STEPS before any coding:

  1. Create User Stories & User Journeys

  2. Create Implementation Plan based on those stories

  3. Align the plan with existing template code

DO NOT SKIP THESE STEPS. DO NOT START CODING UNTIL STEP 4.

📋 PREPARATION PHASE (Do This BEFORE Building)

Step 0: Create Your Project

  1. Log into Kolega Studio (studio.kolega.ai)

  2. Click "+ New Project"

  3. Name it "MoodTracker"

  4. Select "Full Stack App" template

  5. Click "Create Project"

  6. You now have an empty project with template code

Step 1: Create User Stories and User Journeys ONLY

No implementation details, no technical specs - just what users need

Choose ONE Option:

OPTION A: Use External LLM (Recommended)

  1. Open ChatGPT, Claude, or Gemini in another tab

  2. Copy and paste this exact prompt:

Create User Stories and User Journeys for a MoodTracker wellness app. 

Features needed: 
- Users can log their daily mood using emojis 
- Users can see analytics about their mood patterns 
- Users get daily wellness tips 
- There's a marketing page to attract new users 

Write detailed User Stories (As a user, I want to...) and User Journeys (step-by-step flows through the app). 

DO NOT include technical details or implementation specifics.

  1. Work with the LLM until you have comprehensive stories/journeys

  2. Copy the final result to your clipboard

OPTION B: Use Kolega Studio

  1. In Kolega Studio, create New Thread 1 named "User Stories"

  2. Paste this:

Create User Stories and User Journeys for a MoodTracker wellness app. 

Features needed: 
- Users can log their daily mood using emojis 
- Users can see analytics about their mood patterns 
- Users get daily wellness tips 
- There's a marketing page to attract new users 

Create User Stories and User Journeys ONLY. DO NOT create an implementation plan yet. 

DO NOT start coding until I approve the plan.

Step 2: Create the Implementation Plan

Now KS will create the technical plan based on your user stories

If you used Option A (external LLM):

  1. Create New Thread 1 in Kolega Studio named "Implementation Plan"

  2. Paste your User Stories and User Journeys

  3. Then add this exact text:

Based on these User Stories and User Journeys below, create a detailed Implementation Plan with Checklist. 

Requirements: 
- Break it into numbered phases (Phase 1, Phase 2, etc.) 
- Each phase must have checkboxes (- [ ]) for tracking 
- You decide all technical details based on the existing Full Stack App template - Save as implementation_plan.md DO NOT start coding until I approve the plan.

If you used Option B (KS for stories):

  1. Either continue in same thread OR create New Thread 2 named "Implementation Plan"

  2. Type exactly:

Based on the User Stories and User Journeys we created, create a detailed Implementation Plan with Checklist. 

Requirements: 
- Break it into numbered phases (Phase 1, Phase 2, etc.) 
- Each phase must have checkboxes (- [ ]) for tracking 
- You decide all technical details based on the Full Stack App template 
- Save as implementation_plan.md 

DO NOT start coding until I approve the plan.

VERIFY THE PLAN EXISTS:

  1. Click the <> Code Viewer icon

  2. Look for implementation_plan.md (example below)

implementation_plan.md

17.7 KB

  1. Open it and verify it has:

    • Phases numbered clearly

    • Checkboxes next to tasks

    • Technical details KS added

Step 3: CRITICAL - Align Plan with Existing Template

This step saves hours of debugging

Create a NEW Thread named "Gap Analysis"

Type EXACTLY this:

Review the existing codebase from the Full Stack App template and compare it with our implementation_plan.md file. 

Update the implementation_plan.md to align with what already exists in the codebase and template. This prevents conflicts and wasted work. 

Make sure the plan uses the existing React, Vite, MongoDB, and Tailwind setup that's already in the template.

Wait for completion, then verify in Code Viewer that implementation_plan.md was updated.

Step 4: Set Up Environment Variables (If Needed)

Check if your app needs external services and set them up BEFORE building (where possible)

In the SAME thread or create a NEW Thread named "Environment Check"

Type EXACTLY:

Review the implementation_plan.md and identify any external services that will need API keys or environment variables (such as OpenAI, Stripe, Google Maps, email services, authentication services, etc.). 

List any required environment variables that need to be set up before we start building.

If environment variables are needed:

IMPORTANT: You must obtain these API keys from the external service providers first:

After obtaining your keys:

  1. Click the ⚙️ Settings icon (rightmost tab)

  2. Go to "Environment Variables" section

  3. Click "+ Add Variable"

  4. For each variable needed:

    • Enter the variable name (e.g., OPENAI_API_KEY) be sure to follow this naming convention

    • Enter the value (your actual API key from the provider)

    • Click Save

  5. CRITICAL: Click the green status indicator and select "🔄 Reset Sandbox" to apply the variables

  6. Wait for sandbox to restart (green indicator returns)

After environment variables are set, update the plan:

Back in your thread, type:

The following environment variables have been configured: 
[list the variables you added] 

Please update the implementation_plan.md to incorporate these external services into the relevant phases. For example, if we added STRIPE_API_KEY, update payment-related phases to use Stripe. If we added OPENAI_API_KEY, update AI features to use OpenAI. 

Make sure the plan now reflects that these services are available and should be used.

If NO environment variables needed:

  • Proceed directly to Step 5

❗ Why Environment variables matter?

Setting up environment variables at the start of the project will allow the system to build real integrations rather than mock services for these integrations.

To undo mock integrations at a later stage will require significant code changes and increase credit usage.

🚀 BUILDING PHASE (Now You Can Start Coding)

Step 5: Build Phase 1

Create NEW Thread named "Phase 1 Build"

Type EXACTLY:

Proceed with Phase 1 of implementation_plan.md

When complete, type:

Test Phase 1 and mark completed items in implementation_plan.md

Step 6: Build Phase 2

Create NEW thread named "Phase 2 Build"

Type EXACTLY:

Phase 1 is complete. Proceed with Phase 2 of implementation_plan.md

When complete, type:

Test Phase 2 and mark completed items in implementation_plan.md

Step 7-11: Continue Building Each Phase

For EACH remaining phase:

  1. Create NEW Thread named "Phase X Build"

  2. Type: Previous phases complete. Proceed with Phase X of implementation_plan.md

  3. Test and mark complete

Final Step: Deploy

  1. After ALL phases complete, tested and work as planned

  2. Click green Publish button

  3. Select "🚀 Publish latest version"

  4. Your app is live!

🐛 Bug Testing & Fixing Protocol

The Golden Rule of Testing

"Building software is like building a house - you MUST check the quality of each layer before building more on top of it."

Testing After EVERY Phase (CRITICAL)

Before marking ANY phase complete + manually test where possible ie UI:

  1. API Testing (if backend work was done):

Create test scripts for all API endpoints created in this phase. Verify each endpoint works correctly before proceeding.

  1. Functional Testing (for UI/features):

Use the browser agent to test all functionality built in this phase. Click every button, fill every form, test every interaction.

  1. Error Log Review:

Check the console logs and system logs for any errors. 

Fix all errors before marking phase complete.

When You Find a Bug

For Simple Bugs:

Continue in the current thread and ask:

Fix [describe the bug specifically]. 

Here's what's happening: [description or screenshot]

For Complex/UI Bugs:

  1. Create NEW Thread named "Bug Fix - [Description]"

  2. Include screenshot of the issue

  3. Be SPECIFIC:

    • Exact error message

    • What you expected vs what happened

    • Which phase this relates to

  4. Example:

The login button on mobile view is cut off. 

See screenshot. This is from Phase 2. The button should be fully visible and centered.

For Persistent/Difficult Bugs:

Call specialized agents:

Use the investigation agent to analyze why [describe the bug]. Then use think_hard to determine the best fix.

Or:

Use the browser agent to reproduce this bug and capture the exact error. Then fix it.

Bug Prevention Strategy

Check These Early (Hard to Fix Later):

  • Database schemas - Verify in Database Viewer after first data save, manually check data is there in the db and is the data you expect, if not create a New Thread and ask KS to fix the issue

  • API endpoints - Test immediately after creation

  • Environment variables - Confirm they work before building features that need them

  • Mobile responsiveness - Check after each UI phase

If Everything Breaks:

  1. First: Check if sandbox needs reset (green indicator → Reset Sandbox)

  2. Second: Verify all environment variables are set correctly

  3. Third: Check implementation_plan.md - you may have skipped a step

  4. Last Resort: In Project Settings → Revisions, you can revert to earlier version

UI/UX Fine-Tuning Tips

When fixing visual issues:

  • Use separate threads for different UI elements to maintain focus

  • Provide screenshots with annotations

  • Specify exact colours (#hex codes), fonts, and dimensions

  • Reference design systems: "Make it look like Stripe's dashboard"

⚠️ COMMON MISTAKES THAT BREAK EVERYTHING

DON'T DO THESE:

❌ Starting to code without the implementation plan - You'll waste time and credits

❌ Skipping the gap analysis - Your code won't work with the template

❌ Using one thread for everything - You'll hit context limits and confuse the AI

❌ Adding your own technical specs - Let KS decide based on the template

❌ Not testing between phases - Bugs compound and become unfixable

DO THESE INSTEAD:

✅ Follow steps in exact order - No skipping

✅ Create new thread for each phase - Keeps AI focused

✅ Let implementation_plan.md guide everything - It's your single source of truth

✅ Test after each phase - Catch problems early

✅ Trust the process - It works when followed exactly

📊 What Success Looks Like

After following this guide correctly:

  • You'll have a working MoodTracker app

  • Your implementation_plan.md will have all checkboxes marked [x]

  • Each phase was built in its own thread

  • The app works on first deployment

  • You didn't waste time on debugging or rewrites

🆘 If You Get Confused

Lost track of where you are?

  1. Check implementation_plan.md to see what's marked complete

  2. Count your threads to see which phase you're on

  3. Start a new thread for the next unmarked phase

Something not working?

  1. Did you do the gap analysis (Step 3)? If no, you skipped a critical step

  2. Are you in a new thread for this phase? If no, create one

  3. Did you test the previous phase? If no, go back and test

The Golden Rule: When in doubt, check implementation_plan.md - it has all the answers.

This methodology works ONLY when followed exactly. Every step has a purpose. Skip nothing.