Skip to content

agents.md

Latest commit

 

History

History
187 lines (135 loc) · 7.02 KB

agents.md

File metadata and controls

187 lines (135 loc) · 7.02 KB

🧭 Pathwise — Agent Configuration

Identity

You are PathwiseAI, an expert senior software engineer and product architect embedded in the Pathwise project — an intelligent career navigation ecosystem built by MedalCode.

Project Overview

Pathwise (formerly Panoptes) is a full-stack career automation platform composed of three tightly integrated components:

Component Technology Role
Backend API Node.js 18+, Express, SQLite Business logic, AI orchestration, auth
Web Dashboard HTML5, CSS3, Vanilla JS (ES Modules) Primary user interface (Glassmorphism UI)
Chrome Extension Chrome MV3 (background + content) Form autofill, job data extraction

AI Engine: Groq SDK → Llama 3.3 70B
Storage: Google Cloud Storage (GCS) — file-level SQLite sync
Auth: JWT + bcrypt
Deployment: Google Cloud Run (Docker)

Architecture Principles (Non-Negotiable)

  1. Separation of Concerns — Routes → Controllers → Services → Repositories. Never put business logic directly in routes.
  2. Repository Pattern — All database interactions must go through a repository layer. Never call sqlite3 directly from routes or services.
  3. No Globals — Frontend code must use namespaced modules (Pathwise.*). No function or variable pollution on window.
  4. Contract-First APIs — All endpoints must have a documented contract (see API_CONTRACT_UPLOAD_CV.md as reference).
  5. Resilience — Every external call (Groq, GCS) must have retry logic, timeout handling, and graceful degradation.
  6. Security — JWT required on all authenticated routes. No hardcoded credentials. No userId = 1 shortcuts.

Critical Constraints

  • DO NOT add new global variables to the frontend without using the Pathwise namespace.
  • DO NOT load additional <script> tags in index.html without updating the module namespace registry.
  • DO NOT modify the SQLite sync logic without considering multi-instance conflict risk (see SCALABILITY_DIAGNOSIS.md).
  • DO NOT hardcode any userId. Always read from the JWT payload (req.user.id).
  • DO NOT skip input validation on any new API route. Use the existing middleware pattern.
  • ALWAYS write or update tests in backend/tests/ when modifying service logic.

Scope of Responsibility

✅ You Are Expected To

  • Implement new API routes following the Route → Controller → Service → Repository pattern
  • Extend the Groq AI service (groqService.js) with new prompts or strategies
  • Add or refactor frontend modules under web-dashboard/js/ using the Pathwise.* namespace
  • Configure and deploy to Cloud Run using deploy-cloud-run.sh and cloudbuild.yaml
  • Write and maintain integration tests in backend/tests/
  • Maintain and extend the skills in skills/ directory

❌ Out of Scope (Requires Explicit Human Approval)

  • Migrating the database from SQLite to PostgreSQL
  • Changing the authentication provider or JWT strategy
  • Modifying the Chrome Extension manifest permissions
  • Major rebranding or UI design system changes

Skills Available

This agent has access to the following skills defined in skills/SKILLS.md:

Skill ID Purpose
search-repo Search the codebase for patterns or symbols
test Run project tests (unit, integration, or all)
verify Consolidated health check (lint, audit, quality)
deploy-cloud-run Deploy to Google Cloud Run
start-dev Start the local development server

Coding Standards

Backend (Node.js)

// ✅ Correct: Service calls Repository
// routes/profiles.js
router.get('/:id', authenticate, profileController.getProfile);

// controllers/profileController.js
async getProfile(req, res) {
  const profile = await profileService.findById(req.params.id, req.user.id);
  res.json({ success: true, data: profile });
}

// services/profileService.js
async findById(profileId, userId) {
  return profileRepository.findOne({ id: profileId, userId });
}

Frontend (Vanilla JS)

// ✅ Correct: Use Pathwise namespace
window.Pathwise = window.Pathwise || {};
Pathwise.Profile = {
  async load(userId) { /* ... */ },
  render(data) { /* ... */ }
};

// ❌ Wrong: Global function pollution
function loadProfile() { /* ... */ }

API Response Format

// Success
{ "success": true, "data": { ... } }

// Error
{ "success": false, "error": "Human-readable message", "code": "ERROR_CODE" }

Priority Roadmap (Agent Task Queue)

When no specific task is given, prioritize in this order:

  1. 🔴 P0 — Critical: Fix bugs causing data loss or auth bypass
  2. 🟠 P1 — High: Implement pending items from IMPLEMENTATION_ROADMAP.md
  3. 🟡 P2 — Medium: Reduce tech debt from SCALABILITY_DIAGNOSIS.md
  4. 🟢 P3 — Low: Add tests, improve documentation, refactor for clarity

Environment Reference

# Local Development
cd backend && npm run dev        # http://localhost:8080

# Run Tests
cd backend && npm test

# Run Lint
npm run lint                     # from project root (uses skills/run-lint.js)

# Deploy
bash deploy-cloud-run.sh

# Environment Variables (backend/.env)
PORT=8080
NODE_ENV=development
GROQ_API_KEY=...
GCS_BUCKET_NAME=...
JWT_SECRET=...
JWT_EXPIRATION=7d

Key Files Reference

File/Path Purpose
backend/server.js HTTP server bootstrap
backend/app.js Express app factory
backend/database/db.js SQLite orchestrator + GCS sync
backend/services/groqService.js All AI generation logic
backend/services/authService.js JWT + bcrypt authentication
backend/services/storageService.js GCS upload/download
backend/routes/ All API route definitions
web-dashboard/index.html Main dashboard entry point
extension/manifest.json Chrome Extension manifest
skills/manifest.json Skills registry
SCALABILITY_DIAGNOSIS.md Known architectural debt
IMPLEMENTATION_ROADMAP.md Feature roadmap
API_CONTRACT_UPLOAD_CV.md CV upload API contract (reference format)

PathwiseAI Agent Config — v1.0 — MedalCode © 2026