Job-Info/instructions/OPUS_QUICKSTART.md

🚀 Quick Start: Using Opus 4.5 to Scaffold Job-Info-Prod

What You're About to Do

Use Claude Opus 4.5 to scaffold the complete Job-Info-Prod project structure with:

• ✅ Professional folder layout
• ✅ All service files with proper architecture
• ✅ Route handlers with correct patterns
• ✅ Frontend components scaffolding
• ✅ Configuration templates
• ✅ Environment setup
• ✅ Test structure

---

Step 1: Gather the Prompt

Main Prompt Document

File: /home/admin/Job-Info-Test/OPUS_PROMPT_PHASE1.md (671 lines)

Content Summary:

• Dual-token architecture explanation
• Token lifecycle (login → refresh → logout)
• Token storage strategy (localStorage + Valkey)
• Single token check pattern
• Background refresh service
• Offline-first approach
• Complete project structure specification
• Implementation examples
• Tech stack enforcement

Supporting Documents (Optional Reference)

• auth/RULES.md - Implementation rules
• auth/TECH_STACK.md - Technology requirements
• auth/VIEWS.md - UI specifications

---

Step 2: Prepare the Prompt for Opus

Option A: Direct Copy-Paste

1. Open /home/admin/Job-Info-Test/OPUS_PROMPT_PHASE1.md
2. Copy entire content (Ctrl+A, Ctrl+C)
3. Open Claude Opus 4.5
4. Paste content
5. Add instruction below

Option B: Include in Conversation

1. Start new conversation with Opus 4.5
2. Paste the prompt with preamble

---

Step 3: Send to Opus 4.5

Exact Instruction to Give Opus

You are an expert software architect specializing in field-deployed applications.

Your task: Scaffold the complete Job-Info-Prod project structure based on the 
architecture specification provided below.

Requirements:
1. Create all folders and files exactly as specified in the architecture
2. Implement all service files with proper class structure (no implementation, just structure)
3. Create all route handlers with correct signatures and patterns
4. Set up TypeScript configuration (strict mode)
5. Create environment template
6. Create configuration files (package.json, tsconfig.json, etc.)
7. Create test file structure
8. Include comprehensive README for each major folder
9. NO implementation code needed - just structure and patterns
10. All files must follow the architecture specification precisely

The architecture specification follows this document:

[PASTE ENTIRE OPUS_PROMPT_PHASE1.md HERE]

When complete, provide a summary of all created files and folders.

---

Step 4: What Opus Will Produce

Expected Deliverables

Job-Info-Prod/
├── backend/
│   ├── src/
│   │   ├── index.ts
│   │   ├── config/
│   │   │   ├── env.ts
│   │   │   └── constants.ts
│   │   ├── middleware/
│   │   │   ├── auth.ts
│   │   │   ├── errorHandler.ts
│   │   │   └── logger.ts
│   │   ├── routes/
│   │   │   ├── auth.ts
│   │   │   ├── jobs.ts
│   │   │   ├── files.ts
│   │   │   ├── health.ts
│   │   │   └── index.ts
│   │   ├── services/
│   │   │   ├── tokenService.ts
│   │   │   ├── cacheService.ts
│   │   │   ├── pocketbaseService.ts
│   │   │   ├── graphService.ts
│   │   │   └── jobsService.ts
│   │   ├── types/
│   │   │   ├── auth.ts
│   │   │   ├── job.ts
│   │   │   └── common.ts
│   │   └── utils/
│   │       ├── logger.ts
│   │       └── validators.ts
│   ├── tests/
│   │   ├── auth.test.ts
│   │   ├── token-refresh.test.ts
│   │   └── jobs.test.ts
│   ├── package.json
│   ├── tsconfig.json
│   └── README.md
│
├── frontend/
│   ├── public/
│   │   ├── index.html
│   │   ├── signin.html
│   │   ├── offline.html
│   │   └── assets/
│   ├── src/
│   │   ├── main.ts
│   │   ├── auth/
│   │   │   ├── client.ts
│   │   │   ├── pocketbase.ts
│   │   │   └── refresh-loop.ts
│   │   ├── views/
│   │   │   ├── auth-view.ts
│   │   │   ├── landing-view.ts
│   │   │   ├── job-detail-view.ts
│   │   │   └── notes-view.ts
│   │   ├── services/
│   │   │   ├── api-client.ts
│   │   │   ├── cache.ts
│   │   │   ├── state.ts
│   │   │   └── offline.ts
│   │   ├── components/
│   │   │   ├── job-card.ts
│   │   │   ├── file-list.ts
│   │   │   └── sticky-notes.ts
│   │   ├── types/
│   │   │   ├── auth.ts
│   │   │   └── job.ts
│   │   └── styles/
│   │       ├── main.css
│   │       └── tailwind.css
│   ├── tests/
│   ├── package.json
│   ├── tsconfig.json
│   ├── tailwind.config.js
│   ├── postcss.config.js
│   └── README.md
│
├── shared/
│   ├── types/
│   │   ├── auth.ts
│   │   └── job.ts
│   └── constants/
│       └── index.ts
│
├── docs/
│   ├── ARCHITECTURE.md
│   ├── API.md
│   ├── TOKEN_LIFECYCLE.md
│   ├── OFFLINE_STRATEGY.md
│   └── DEPLOYMENT.md
│
├── .env.example
├── .gitignore
├── package.json
├── tsconfig.json
├── README.md
└── CHANGELOG.md

Key Files Opus Will Create

Backend Structure:

• Service classes (proper signatures, ready for implementation)
• Route handlers (with proper HTTP methods and patterns)
• Middleware (error handling, auth, logging)
• Configuration files (TypeScript, environment)

Frontend Structure:

• Token client class (for ensureToken pattern)
• View files (with proper structure)
• API client (for token injection)
• Component templates

Configuration:

• package.json (with dependencies)
• tsconfig.json (strict mode)
• .env.example (all variables)

---

Step 5: After Opus Completes

What to Do Next

1. Review the scaffolding

   • Check folder structure matches specification
   • Verify all files created
   • Review service signatures

2. Save to Job-Info-Prod folder (temporary staging)

   # Create new folder
   mkdir -p /home/admin/Job-Info-Prod
   
   # Move files from Opus output
   cp -r [opus-output]/* /home/admin/Job-Info-Prod/
   

3. Initialize git

   cd /home/admin/Job-Info-Prod
   git init
   git add .
   git commit -m "Initial scaffolding with Opus 4.5"
   

4. Install dependencies

   cd /home/admin/Job-Info-Prod
   bun install
   

5. Verify structure

   # Check TypeScript compilation
   bun --bun src/index.ts
   
   # Or use TypeScript compiler
   npx tsc --noEmit
   

---

Step 6: Next Phase - Sonnet 4.5 Implementation

Once Job-Info-Prod is scaffolded, use Sonnet 4.5 for implementation:

What Sonnet Will Implement

1. Backend implementation

   • TokenRefreshService (30-min background loop)
   • TokenService (refresh logic)
   • Auth routes (login, logout, refresh)

2. Frontend implementation

   • TokenClient (ensureToken pattern)
   • API integration
   • View rendering

3. Services

   • Redis cache operations
   • PocketBase integration
   • Microsoft Graph integration

Sonnet Prompt Will Include

• Implementation patterns from RULES.md
• Code examples from OPUS_PROMPT_PHASE1.md
• Tech stack requirements from TECH_STACK.md

---

Critical Notes for Opus

Structure Opus Should Follow

• Use TypeScript interfaces for all types
• Create service classes with proper methods
• Use async/await patterns
• Include JSDoc comments for class methods
• Group related files in folders

What NOT to Include

• ❌ Implementation code (just structure)
• ❌ Database migrations (handled by PocketBase)
• ❌ Build scripts (Bun handles this)
• ❌ Production secrets (use .env.example)

What MUST Include

• ✅ All folder structure
• ✅ All file names exactly as specified
• ✅ Service class signatures
• ✅ Route handler patterns
• ✅ TypeScript configuration
• ✅ Environment template
• ✅ README files

---

File References

Document	Purpose	Location
OPUS_PROMPT_PHASE1.md	Main scaffolding prompt	/home/admin/Job-Info-Test/OPUS_PROMPT_PHASE1.md
RULES.md	Implementation rules	/home/admin/Job-Info-Test/auth/RULES.md
TECH_STACK.md	Technology enforcement	/home/admin/Job-Info-Test/auth/TECH_STACK.md
ARCHITECTURE_CONFIRMED.md	Status overview	/home/admin/Job-Info-Test/ARCHITECTURE_CONFIRMED.md
MIGRATION_READY.md	Phase plan	/home/admin/Job-Info-Test/MIGRATION_READY.md

---

Success Criteria

After Opus completes, you should have:

• ✅ All folders created
• ✅ All files scaffolded
• ✅ TypeScript compiles with no errors
• ✅ All imports resolve correctly
• ✅ Service classes have proper signatures
• ✅ Routes match specification
• ✅ Configuration templates created
• ✅ Tests structure ready
• ✅ README files in each major folder
• ✅ .gitignore configured

---

Troubleshooting

If Opus Creates Files in Wrong Structure

• Mention the specific architecture from OPUS_PROMPT_PHASE1.md
• Ask Opus to reorganize to match exact structure

If Type Definitions are Missing

• Opus may have skipped some types
• Ask specifically for shared/types/ files

If Dependencies Are Missing

• Review package.json for required packages
• Should include: Hono, ioredis, TypeScript, Tailwind

---

Ready?

1. ✅ Copy OPUS_PROMPT_PHASE1.md
2. ✅ Paste into Opus 4.5
3. ✅ Add the instruction from Step 3
4. ✅ Let Opus scaffold
5. ✅ Review output
6. ✅ Move to Job-Info-Prod folder
7. ✅ Commit to git
8. ✅ Then move to Sonnet 4.5 for implementation

Estimated time with Opus: 15-30 minutes 🚀