Imported from stu-jc/credit-bridge (AGENTS.md). Install upstream with npx skills add stu-jc/credit-bridge. Copyright stays with the author.

CreditBridge Agent Instructions

Use this file whenever creating, prompting, or coordinating agents for CreditBridge work.

Project Goal

CreditBridge helps exchange students and universities turn messy subject outlines into clear, explainable credit-transfer recommendations.

The demo should emphasize:

• structured subject extraction
• explainable subject matching
• human-in-the-loop institutional review
• approval-pack generation as the hero moment

Shared Build Rules

• Keep the MVP narrow and demo-ready.
• Prefer the existing Next.js, Convex, and local TypeScript structure.
• Use mock/demo data first when live services are not required.
• Keep final academic approval with the institution; do not imply guaranteed equivalency.
• Surface missing information and risks instead of hiding uncertainty.
• Do not overbuild authentication, permissions, live handbook integrations, or degree auditing.

Agent Coordination

Agents must receive a bounded write scope and must not edit outside that scope.

When multiple agents are used:

• split work by file ownership
• avoid overlapping write sets
• tell each agent they are not alone in the codebase
• tell each agent not to revert edits made by others
• require each agent to list changed files in its final response

Preferred Workstreams

Frontend Shell

Scope:

• app/**
• components/**
• app/globals.css

Build:

• landing page
• student dashboard and search results
• institution dashboard and upload screen
• match detail page
• approval-pack page

Acceptance:

• full demo flow is navigable
• UI is dashboard-style and polished
• approval pack is the strongest screen

Convex Backend

Scope:

• convex/**

Build:

• subject schema
• match schema
• student profile schema
• uploaded file metadata
• institution review records
• approval pack records
• queries and mutations for CRUD/review flow

Acceptance:

• frontend can later create, read, and update subjects and matches
• review status can be changed by institution staff
• approval packs can be saved and retrieved

AI And Matching

Scope:

• lib/ai/**
• lib/matching/**
• lib/demo-data.ts

Build:

• subject extraction prompts
• subject matching prompts
• approval-pack prompts
• deterministic demo scoring utilities
• candidate ranking utilities
• stable demo dataset

Acceptance:

• selecting a home subject returns ranked host subjects
• each match has score, explanation, strengths, risks, and missing information
• OpenAI integration points are clear but do not block static demo use

Demo Content

Scope:

• docs/**
• README.md

Build:

• 3-minute demo script
• judge-facing pitch
• before/after workflow summary

Acceptance:

• demo can be completed in under 3 minutes
• approval-pack moment is clear
• OpenAI, Convex, and human-review story is explicit

Agent Prompt Template

You are working in /Users/jc/Developer/credit-bridge on CreditBridge.

Read AGENTS.md first and follow it.

You are not alone in the codebase. Do not revert edits made by others. Keep your write scope to:

- <paths>

Task:

<specific task>

Acceptance criteria:

- <criteria>

Final response:

- list changed files
- summarize the implementation
- mention any tests or checks run