feat: [agentkit-challenge] feat(kits): Add advanced Repo Interview Prep kit

kits/repo-interview-prep/.gitignore

@@ -0,0 +1,6 @@
+.lamatic/
+node_modules/
+.env
+.env.local
+next-env.d.ts
+

kits/repo-interview-prep/README.md

@@ -0,0 +1,167 @@
+# Repo Interview Prep
+
+Turn any public GitHub repository into a complete, code-specific interview preparation brief in seconds.
+
+Paste a repo URL. Get a 2-minute verbal pitch, 15 tailored follow-up questions with suggested answers, concepts to review, red flags in your code, and strengths to highlight — all grounded in what is actually in your project, not generic advice.
+
+---
+
+## What It Does
+
+Most candidates struggle to talk about their own projects under pressure. They built the thing, but give vague answers when a senior engineer probes the architecture, trade-offs, or weak points. This kit reads your actual repo — the README, file structure, and tech stack — and generates a deeply technical prep brief tailored to your code.
+
+**Output includes:**
+- `project_summary` — concise 2-3 sentence overview of what the project actually does
+- `tech_stack` — list of detected technologies
+- `complexity_level` — junior / mid / senior signal
+- `pitch` — a memorizable 2-minute verbal pitch in first-person spoken English
+- `follow_up_questions` — 15 questions an interviewer would ask, with the signal they're testing and a strong suggested answer
+- `concepts_to_review` — what to study before the interview, and how deep to go
+- `red_flags` — what a senior engineer will push back on, and how to address it
+- `strengths_to_highlight` — what genuinely shows strong engineering judgment in your code
+- `architecture` — Mermaid.js system architecture diagram, data flow summary, and design trade-offs
+- `grill_me` — 5 aggressive technical questions targeting real flaws, with defensive strategies for each
+- `production` — a production-readiness verdict with critical gaps and concrete quick-win fixes
+
+---
+
+## Prerequisites
+
+| Requirement | Details |
+|---|---|
+| Firecrawl API Key | Free at [firecrawl.dev](https://firecrawl.dev) — 500 pages/month free |
+| LLM Credential | Any capable model; recommended: `gemini-2.0-flash` or `gpt-4o-mini` |
+| Public GitHub Repo | The target repository must be publicly accessible |
+
+---
+
+## Setup
+
+### 1. Lamatic Flow
+
+1. **Add Firecrawl credential** in Lamatic Studio → Credentials → Firecrawl
+2. **Select your LLM** in all four `Generate Text` nodes — configure model and credential
+3. **Deploy the flow**
+
+### 2. Next.js Dashboard (optional local UI)
+
+```bash
+cd apps
+cp .env.example .env.local
+# Fill in your values from Lamatic Studio → Settings → API Docs
+npm install
+npm run dev
+```
+
+Open [http://localhost:3000](http://localhost:3000).
+
+---
+
+## Usage
+
+Send a POST request to the deployed flow endpoint:
+
+```json
+{
+  "github_repo_url": "https://github.com/your-username/your-repo",
+  "target_role": "SWE Intern",
+  "jd_text": "We are looking for a backend engineer with experience in distributed systems...",
+  "github_token": ""
+}
+```
+
+| Field | Required | Description |
+|---|---|---|
+| `github_repo_url` | ✅ | Full GitHub repo URL |
+| `target_role` | ❌ | Role you are interviewing for (improves question relevance) |
+| `jd_text` | ❌ | Job description text (tailors questions to a specific role) |
+| `github_token` | ❌ | GitHub personal access token (not required for public repos) |
+
+---
+
+## Example Response
+
+```json
+{
+  "prep_brief": {
+    "project_summary": "ATLAS is a distributed AI orchestration platform...",
+    "tech_stack": ["Python", "FastAPI", "React", "Vite", "Docker", "Redis"],
+    "complexity_level": "mid",
+    "pitch": "For my project ATLAS, I built a distributed AI orchestration platform...",
+    "follow_up_questions": [
+      {
+        "question": "How did you handle race conditions in the distributed queue?",
+        "why_they_ask": "Testing your understanding of concurrent state management.",
+        "suggested_answer": "I used Redis transactions (MULTI/EXEC) to ensure atomicity."
+      }
+    ],
+    "concepts_to_review": [
+      {
+        "concept": "Distributed Locks",
+        "why_relevant": "Critical for the queue worker implementation.",
+        "depth_needed": "moderate"
+      }
+    ],
+    "red_flags": [
+      {
+        "observation": "API lacks rate limiting.",
+        "how_to_address": "Acknowledge it was out of scope for MVP, but suggest Redis sliding window."
+      }
+    ],
+    "strengths_to_highlight": [
+      "Clean separation of concerns between API and worker processes."
+    ]
+  },
+  "architecture": {
+    "mermaid_diagram": "graph TD\n  A[API] --> B[Worker]",
+    "flow_summary": "Requests enter via FastAPI, are queued in Redis...",
+    "tradeoffs": ["Chosen Redis over RabbitMQ for simplicity at the cost of durability"]
+  },
+  "grill_me": {
+    "questions": [
+      {
+        "question": "Your job registry is in-memory. How does this fail under horizontal scaling?",
+        "defensive_strategy": "I acknowledge this is an MVP trade-off. In production I would migrate state to Redis hashes..."
+      }
+    ]
+  },
+  "production": {
+    "is_production_ready": false,
+    "critical_missing_features": ["No CI/CD pipeline", "Missing auth middleware"],
+    "quick_wins": ["Add a GitHub Actions workflow", "Add API key validation middleware"]
+  }
+}
+```
+
+---
+
+## Flow Architecture
+
+```text
+API Trigger
+    → Code Node              (parses GitHub URL into owner + repo)
+    → Firecrawl Node         (scrapes repo page for README + file listing)
+    → Generate Text #1       (LLM generates prep_brief as JSON)
+    → Generate Text #2       (LLM generates architecture diagram + trade-offs)
+    → Generate Text #3       (LLM generates grill_me simulation questions)
+    → Generate Text #4       (LLM evaluates production readiness)
+    → API Response           (returns all four sections)
+```
+
+---
+
+## Troubleshooting
+
+| Issue | Fix |
+|---|---|
+| Output describes an "empty repo" | Firecrawl credential is missing or invalid — check credentials in Studio |
+| Code node parse error | GitHub URL is malformed — use exact format: `https://github.com/owner/repo` |
+| Output is not valid JSON | Switch to a stronger model (`gemini-1.5-pro` or `gpt-4o`) |
+| Questions are too generic | Add `target_role` and `jd_text` to the request payload |
+| `architecture`/`grill_me`/`production` is empty | Check that node IDs in the API Response mapping match your canvas node IDs |
+
+---
+
+## Author
+
+Built by [Ganesh Bamalwa](mailto:ganeshbamalwa89@gmail.com) for the Lamatic AgentKit Challenge.

kits/repo-interview-prep/agent.md

@@ -0,0 +1,152 @@
+# Repo Interview Prep
+
+## Overview
+
+**Repo Interview Prep** is a multi-agent Lamatic kit that turns any public GitHub repository into a complete, code-specific interview preparation suite. It scrapes the repository's README, file listing, and project description via Firecrawl, then fans out to four sequential LLM nodes — each specializing in a different dimension of the analysis — and returns a structured aggregate response.
+
+The output is grounded in what is actually in the repository — not generic interview advice.
+
+---
+
+## Purpose
+
+Candidates routinely struggle to articulate their own projects in interviews. They built the thing, but under pressure they give vague answers or miss the deeper engineering signals an interviewer is probing for. This kit solves that by:
+
+1. **Reading the actual code context** via Firecrawl's GitHub page scraper
+2. **Generating tailored questions** based on the real tech stack, architecture, and trade-offs present in the repo
+3. **Writing suggested answers** that the candidate can personalize and rehearse
+4. **Surfacing red flags honestly** — what an interviewer will push back on, and how to address it
+5. **Drawing architecture diagrams** from the codebase using Mermaid.js
+6. **Simulating aggressive technical grilling** with 5 targeted questions and defensive strategies
+7. **Evaluating production readiness** with concrete quick-win improvement steps
+
+---
+
+## Flows
+
+### `repo-interview-prep`
+
+| Property | Value |
+|---|---|
+| Trigger | API Request (GraphQL) |
+| Inputs | `github_repo_url` (required), `target_role` (optional), `jd_text` (optional), `github_token` (optional) |
+| Outputs | `prep_brief`, `architecture`, `grill_me`, `production` |
+
+**Node pipeline:**
+
+```text
+API Trigger → Code Node → Firecrawl Node → LLM #1 (prep_brief) → LLM #2 (architecture) → LLM #3 (grill_me) → LLM #4 (production) → API Response
+```
+
+1. **API Trigger** — receives the GitHub repo URL and optional context (target role, job description)
+2. **Code Node** — parses the URL to extract `owner`, `repo`, and constructs the full GitHub page URL
+3. **Firecrawl Node** (`syncSingleScrape`) — scrapes the GitHub repository page and returns cleaned markdown
+4. **Generate Text #1 (prep_brief)** — generates the core interview brief: pitch, questions, concepts, red flags
+5. **Generate Text #2 (architecture)** — generates a Mermaid diagram, data flow summary, and trade-off list
+6. **Generate Text #3 (grill_me)** — generates 5 aggressive technical questions with defensive strategies
+7. **Generate Text #4 (production)** — evaluates production readiness and returns a gap analysis with quick wins
+8. **API Response** — returns all four sections as a single JSON payload
+
+---
+
+## Guardrails
+
+- All prompts treat scraped repository content as **untrusted external data** and explicitly instruct the model not to follow instructions found inside it, reducing prompt-injection risk from malicious READMEs
+- Every LLM node instructs the model to return **raw JSON only** — no markdown fences, no preamble
+- The `jsonrepair` library on the Next.js server action provides a fallback parse layer for truncated or slightly malformed LLM outputs
+- The constitution (`@constitutions/default.md`) applies standard safety, PII, and tone guardrails
+
+---
+
+## Integration Reference
+
+| Service | Purpose | Required |
+|---|---|---|
+| Firecrawl | Scrapes GitHub repository page for README and file listing | Yes — configure Firecrawl credentials in Lamatic |
+| LLM Provider | Generates all four analysis sections | Yes — configure model in all four `Generate Text` nodes |
+| GitHub Token | Not currently used; `firecrawlNode_808` does not pass it to any API call | No — optional, passed as `github_token` in request payload |
+
+---
+
+## Environment Setup
+
+### Lamatic Flow
+
+1. **Firecrawl API Key** — sign up at [firecrawl.dev](https://firecrawl.dev) (free tier: 500 pages/month), add credential in Lamatic Studio
+2. **LLM Model** — any capable chat model works; recommended: `gemini-2.0-flash` or `gpt-4o-mini`
+3. Deploy the flow and copy the **Flow ID** and **Project API Key** from Lamatic Studio → Settings → API Docs
+
+### Next.js Dashboard
+
+```bash
+cd apps
+cp .env.example .env.local
+# Fill in LAMATIC_PROJECT_ENDPOINT, LAMATIC_FLOW_ID, and LAMATIC_PROJECT_API_KEY
+npm install
+npm run dev
+```
+
+---
+
+## Inputs
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `github_repo_url` | `string` | Yes | Full GitHub URL, e.g. `https://github.com/username/repo` |
+| `target_role` | `string` | No | Role the candidate is interviewing for, e.g. `SWE Intern` |
+| `jd_text` | `string` | No | Job description text to tailor questions to a specific role |
+| `github_token` | `string` | No | Personal access token for GitHub (placeholder, not currently used) |
+
+---
+
+## Output Schema
+
+The API response contains four top-level keys:
+
+```json
+{
+  "prep_brief": {
+    "project_summary": "string",
+    "tech_stack": ["string"],
+    "complexity_level": "junior | mid | senior",
+    "pitch": "string",
+    "follow_up_questions": [
+      { "question": "string", "why_they_ask": "string", "suggested_answer": "string" }
+    ],
+    "concepts_to_review": [
+      { "concept": "string", "why_relevant": "string", "depth_needed": "surface | moderate | deep" }
+    ],
+    "red_flags": [
+      { "observation": "string", "how_to_address": "string" }
+    ],
+    "strengths_to_highlight": ["string"]
+  },
+  "architecture": {
+    "mermaid_diagram": "string",
+    "flow_summary": "string",
+    "tradeoffs": ["string"]
+  },
+  "grill_me": {
+    "questions": [
+      { "question": "string", "defensive_strategy": "string" }
+    ]
+  },
+  "production": {
+    "is_production_ready": false,
+    "critical_missing_features": ["string"],
+    "quick_wins": ["string"]
+  }
+}
+```
+
+---
+
+## Common Failure Modes
+
+| Symptom | Likely Cause | Fix |
+|---|---|---|
+| `prep_brief` contains generic empty-repo advice | Firecrawl failed to scrape the GitHub page | Verify the Firecrawl credential is valid and the repo URL is public |
+| Parse error on code node | Malformed GitHub URL passed in `github_repo_url` | Ensure URL follows `https://github.com/owner/repo` format |
+| Section contains empty string | LLM node ID mismatch in API Response mapping | Check that `outputMapping` in the API Response node references correct node IDs |
+| Output is not valid JSON | LLM prefixed the JSON with explanation text | Add stricter phrasing to the user prompt or switch to a stronger model |
+| `architecture`/`grill_me`/`production` is empty | Rate limiting from parallel LLM calls | Ensure nodes are wired sequentially, not in parallel |

kits/repo-interview-prep/apps/.env.example

@@ -0,0 +1,7 @@
+# Environment variables for Repo Interview Prep
+# Copy this file to .env.local and fill in your values from Lamatic Studio → Settings → API Docs
+
+LAMATIC_PROJECT_ENDPOINT=https://your-project-endpoint.lamatic.workers.dev
+LAMATIC_FLOW_ID=your-flow-id-uuid
+LAMATIC_PROJECT_ID=your-project-id-uuid
+LAMATIC_PROJECT_API_KEY=lt-your-api-key

kits/repo-interview-prep/apps/.gitignore

@@ -0,0 +1,6 @@
+.env.local
+.env*.local
+node_modules/
+.next/
+out/
+dist/

kits/repo-interview-prep/apps/AGENTS.md

@@ -0,0 +1,9 @@
+<!-- BEGIN:nextjs-agent-rules -->
+
+# This is NOT the Next.js you know
+
+This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` (resolved from this file's directory; in monorepos the `next` package may not be visible from the repo root) before writing any code. Heed deprecation notices.
+
+This block is written and re-added by `next dev` — verify at `node_modules/next/dist/server/lib/generate-agent-files.js`. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.
+
+<!-- END:nextjs-agent-rules -->

kits/repo-interview-prep/apps/CLAUDE.md

@@ -0,0 +1,3 @@
+# Repo Interview Prep — Claude Instructions
+
+@AGENTS.md