Merge pull request #24 from javiera-vasquez/feature/improve-tailor-server-inner-functionality

feat: Implement section registry system and enhance template architecture

Author: javiera-vasquez

.claude/agents/job-tailor.md

@@ -56,7 +56,7 @@ This sub-agent specializes in analyzing job applications and creating tailored r
 - Technical expertise must include `resume_title` and prioritized `skills` arrays (max 4 categories)
 - Flatten soft skills into single array (max 12 skills)
 - Generate metadata.yaml from job_analysis using transformation rules in `resume-data/mapping-rules/metadata.yaml`
-- Metadata must include all required fields: company, folder_path, available_files, position, primary_focus, job_summary, job_details (nested), last_updated
+- Metadata must include all required fields: company, folder_path, available_files, position, primary_focus, job_summary, job_details (nested), active_template, last_updated
 - Format job_details with: company, location, experience_level, employment_type, must_have_skills (top 5), nice_to_have_skills, team_context, user_scale
 - Job summary must be concise (max 100 characters)
 - Preserve data integrity - no fabricated content, only selection and emphasis
@@ -176,6 +176,7 @@ job_details:
   nice_to_have_skills: ['Vector databases', 'AWS', 'Docker']
   team_context: 'AI team of 50+ engineers, cross-functional collaboration'
   user_scale: '10 million users globally'
+active_template: 'modern'
 last_updated: '2025-09-30T12:00:00Z'
 ```
 
@@ -269,7 +270,7 @@ job_analysis:
 
 **Metadata** (from `resume-data/mapping-rules/metadata.yaml`):
 
-- **Required Fields**: company, folder_path, available_files, position, primary_focus, job_summary, job_details, last_updated
+- **Required Fields**: company, folder_path, available_files, position, primary_focus, job_summary, job_details, active_template, last_updated
 - **Job Summary**: Max 100 characters
 - **Must-Have Skills in job_details**: Max 5 items (top priority from job_analysis)
 - **Nice-to-Have Skills in job_details**: Max 5 items

.claude/agents/tailor-generate-assets.md

@@ -218,12 +218,14 @@ resume:
   independent_projects: # Projects scored by technology relevance
     - name: 'AI Chat Application'
       description: 'React/TypeScript chat app with GPT integration'
-      technologies: ['React', 'TypeScript', 'LangChain', 'GPT-4']
       url: 'https://github.com/johndoe/ai-chat'
+      achievements:
+        - 'Built with React, TypeScript, LangChain, and GPT-4'
+        - 'Implemented real-time chat with AI-powered responses'
 
   education:
     - institution: 'Stanford University'
-      degree: 'BS Computer Science'
+      program: 'BS Computer Science'
       location: 'Stanford, CA'
       duration: '2010 - 2014'
 ```
@@ -235,6 +237,7 @@ version: '2.0.0'
 analysis_date: '2025-09-19'
 
 cover_letter:
+  name: 'John Doe' # Top-level required field
   company: 'TechCorp' # From metadata
   position: 'Senior AI Engineer' # From metadata
   job_focus: # REQUIRED: copied from job_analysis.yaml
@@ -248,7 +251,6 @@ cover_letter:
   date: '2025-09-30'
 
   personal_info:
-    name: 'John Doe'
     address: '456 Innovation Drive, San Francisco, CA'
     email: 'john.doe@example.com'
     phone: '+1 (555) 555-5555'
@@ -282,6 +284,7 @@ cover_letter:
 - job_focus array is REQUIRED (copy from job_analysis.yaml)
 - job_focus weights must sum to 1.0
 - Body must be array of strings (200-400 words total)
-- Required fields: company, position, job_focus, primary_focus, date, personal_info, content
+- Required fields: name, company, date, personal_info, content
+- Optional fields: position, job_focus, primary_focus
 
 When you receive a company name, first validate prerequisites exist, load all required data, apply specialty-based scoring for content selection, transform data following mapping rules, generate both files, **validate both files and fix any errors**, and ensure all content is truthful and optimized for the specific job requirements.

.claude/commands/tailor.md

@@ -1,11 +1,21 @@
 ---
-allowed-tools: Bash(bun run set-env), SlashCommand, BashOutput
+allowed-tools: Bash(bun run set-env), BashOutput
 description: Set CC in /tailor mode, Ask claude for changes and improvements to the application assets  | argument-hint company-name
 ---
 
-# Tailor Company Context Command
+# Tailor Mode - Collaborative Resume & Cover Letter Editing
 
-Set the active company context for tailored resume operations and start the development server with automatic validation and hot reload.
+This command activates **tailor mode**, where you (Claude) become the user's active collaborator for refining and improving their resume and cover letter for a specific company.
+
+**Your role in tailor mode:**
+
+- Be a proactive editor and writing coach
+- Suggest improvements to content, tone, and **structure**
+- Implement changes directly to YAML files based on user feedback
+- Ensure all edits align with the job posting requirements
+- Validate changes in real-time and fix any issues immediately
+
+The technical infrastructure (server, file watching, validation) runs in the background to support this collaborative editing workflow.
 
 ## Usage
 
@@ -18,41 +28,53 @@ Set the active company context for tailored resume operations and start the deve
 ### 1. User Invokes Command
 
 ```
-/tailor tech-corp
+/tailor company-name
 ```
 
 ### 2. Claude Sets Context
 
-Runs `bun run set-env -C tech-corp`:
+Runs `bun run set-env -C company-name`:
 
-- Validates company folder exists at `resume-data/tailor/tech-corp/`
+- Validates company folder exists at `resume-data/tailor/company-name/`
 - Validates required files (`metadata.yaml`, `job_analysis.yaml`)
 - Updates `.claude/tailor-context.yaml` automatically
-- Returns structured JSON with company details
+- Returns formatted output with company context details
 
 **Exit codes:**
 
 - `0` = Success → Continue to step 3
 - `1` = Failure → Display error and stop
 
+**Example output:**
+
+```
+[10:00:00] [set-env] ✅ Context set • Tech-Corp • 4 file(s)
+[10:00:00] [set-env]    -Path: resume-data/tailor/tech-corp
+[10:00:00] [set-env]    -Position: Senior Frontend Engineer - Web
+[10:00:00] [set-env]    -Focus: senior_engineer + [react, typescript, frontend]
+[10:00:00] [set-env]    -Files: metadata.yaml, job_analysis.yaml, resume.yaml, cover_letter.yaml
+[10:00:00] [set-env] 🚀 All good, please start the tailor-server
+```
+
 ### 3. Claude Starts Development Server
 
-Invokes `/tailor-server` slash command:
+Runs `bun run tailor-server`:
 
 - Starts file watcher monitoring `resume-data/tailor/`
 - Enables automatic data regeneration on file changes
 - Launches browser preview with hot reload
 - Provides real-time validation feedback
 
-### 4. Claude Displays Context Summary
+**Note:** After starting the server, only check one the `🚀 Tailor server ready` log to confirm startup. Vite and Bun handle the HTTP server automatically in the background no need to wait for additional Vite startup logs.
+
+### 4. Claude Confirms Server is Running
+
+After seeing the "Tailor server ready" log, Claude should confirm the setup:
 
 ```
-✅ Active company context: company-name
-📁 Path: resume-data/tailor/[company-name]
-📄 Files: metadata.yaml, job_analysis.yaml, resume.yaml, cover_letter.yaml
-🎯 Position: actual possition described on publication
-🔧 Focus: main roll + [top 3 skill to have]
-🌐 Dev server: http://localhost:3000
+✅ Tailor mode active for [company-name]
+🌐 Dev server running at http://localhost:3000
+📁 Watching: resume-data/tailor/[company-name]
 
 What would you like to work on? I can help you with:
 • Refine resume summary or professional experience
@@ -85,53 +107,90 @@ Claude edits files in `resume-data/tailor/tech-corp/`:
 - `job_analysis.yaml` - Job requirements analysis
 - `metadata.yaml` - Company/position details
 
-### Step 3: System Auto-Validates
+### Step 3: System Auto-Validates (with Debouncing)
+
+File watcher triggers automatic pipeline after 300ms of inactivity:
+
+Pipeline: File change(s) → Debounce delay → YAML parsing → Zod schema validation → TypeScript generation → Hot reload
 
-File watcher triggers automatic pipeline:
+**Key insight:** Multiple rapid edits are batched together automatically, so you don't need to wait between small changes - just make all related edits and the system will validate once.
+
+### Step 4: Smart Validation Checking
+
+Use `BashOutput` strategically based on edit risk level:
+
+**High-risk edits (ALWAYS check):**
+
+- Structural changes (adding/removing sections, changing schema fields)
+- First edit after entering tailor mode
+- User explicitly asks "did that work?" or mentions seeing errors
+- Batch of multiple significant changes
+
+**Low-risk edits (Trust the system):**
+
+- Text refinements (rewording, improving clarity)
+- Typo fixes and grammar improvements
+- Changing metrics or dates
+- Single-field updates (e.g., updating one job description)
+
+**How to check:** Use `BashOutput` to read the tailor-server logs. Look for:
+
+- `✅ [filename] → Regenerated (X.Xs)` = Success, continue
+- `❌ [filename] → Failed (X.Xs)` = Error occurred, must fix immediately
+
+**Example failure output:**
 
 ```
-[file-watcher] Tailor data changed: tech-corp/resume.yaml
-[tailor-server] 🔄 Regenerating data for company: tech-corp
-[generate-data] Validating application data
+❌ resume.yaml → Failed (0.1s)
+[10:24:34] [generate-data] Application data validation failed:
+[10:24:34] [generate-data]   • resume.name: Required (received: undefined)
+[10:24:34] [generate-data]     → in resume-data/tailor/tech-corp/resume.yaml
+💡 Fix the errors above and save to retry
 ```
 
-Pipeline: File change → YAML parsing → Zod schema validation → TypeScript generation → Hot reload
+### Step 5: Communicate Like a Collaborative Editor
 
-### Step 4: Claude Checks Validation Result
+**Don't just execute - collaborate:**
 
-**CRITICAL:** After each edit, Claude MUST use `BashOutput` to check server logs.
-
-**Success path:**
+❌ **Robot mode:**
 
 ```
-[generate-data] ✅ Application data validation passed
-[generate-data] Writing TypeScript module to src/data/application.ts
-[tailor-server] ✅ Data regenerated successfully
-[tailor-server] Hot reload will pick up changes automatically
+"I've updated the resume summary. Done."
 ```
 
-**Failure path:**
+✅ **Collaborative mode:**
 
 ```
-[tailor-server] Application data validation failed:
-[tailor-server]   • resume.contact: Required (received: undefined)
-[tailor-server]     → in resume-data/tailor/tech-corp/resume.yaml
-[tailor-server] 💡 Fix the data issues and try again
+"I'm thinking we should emphasize your React expertise more prominently since
+it's mentioned 5 times in the job posting. Here's what I'm changing:
+
+Before: 'Frontend engineer with experience in modern web technologies'
+After: 'React specialist with 10+ years building scalable web applications'
+
+This directly addresses their requirement for 'Expert-level React skills'.
+What do you think?"
 ```
 
-### Step 5: Claude Responds Based on Result
+**Guidelines for communication:**
+
+- **Explain your reasoning** - Why are you making this change?
+- **Show before/after** - Let them see what you're modifying
+- **Ask for input** - "Does this capture your experience accurately?"
+- **Be proactive** - Suggest improvements, don't just wait for requests
+- **Reference the job posting** - Connect changes to requirements
+- **Offer alternatives** - "We could also phrase it as..."
 
-**If validation passes:**
+**After successful edits:**
 
-- Confirm changes to user
-- Mention browser preview has updated
-- Proceed with next task or await further instructions
+- Confirm changes briefly: "Updated! The preview should refresh in a moment."
+- Ask: "Want to tackle another section, or shall we review what we've done?"
+- Suggest next steps: "The summary looks great now. Should we strengthen the experience section?"
 
-**If validation fails:**
+**When validation fails:**
 
-- Fix the validation error immediately
-- Re-check logs with `BashOutput`
-- Verify fix was successful before responding to user
+- Fix immediately and transparently: "Oops, I made a syntax error. Fixing that now..."
+- Don't mention technical details unless relevant
+- Re-verify the fix before responding
 
 ## Company Folder Structure
 
@@ -143,6 +202,54 @@ resume-data/tailor/company-name/
 └── cover_letter.yaml    # Tailored cover letter content
 ```
 
+## Template Manipulation (Advanced)
+
+Claude can perform three specific template-level modifications:
+
+### 1. Switch Active Template
+
+Change `active_template` in the company's `metadata.yaml` file (e.g., `resume-data/tailor/tech-corp/metadata.yaml`):
+
+- `modern` - Two-column layout, accent colors
+- `classic` - Single-column, monochrome
+
+**Always check BashOutput after template switches.**
+
+### 2. Add/Remove/Modify Sections
+
+Edit section content in `resume.yaml` and `job_analysis.yaml`:
+
+- Add/remove entries in `professional_experience`, `independent_projects`, `education`, etc.
+- Modify `job_analysis` sections: `requirements`, `responsibilities`, `candidate_alignment`, etc.
+
+**Risk levels:**
+
+- Low: Adding items within existing sections
+- High: Adding/removing top-level sections (always check BashOutput)
+
+### 3. Change Section Order
+
+Modify `order` property in `src/templates/{classic|modern}/section-registry.ts`:
+
+```typescript
+// Lower numbers render first (10 before 20)
+{ id: 'education', order: 20 },  // Changed from 30 to appear earlier
+{ id: 'summary', order: 30 },    // Changed from 20 to appear later
+```
+
+**Always check BashOutput and browser preview after order changes.**
+
+**Files you can modify:**
+
+- ✅ `metadata.yaml` (active_template)
+- ✅ `resume.yaml` / `job_analysis.yaml` (sections)
+- ✅ `src/templates/{template}/section-registry.ts` (order only)
+
+**Files you cannot modify:**
+
+- ❌ `.claude/tailor-context.yaml` (auto-generated, edit metadata.yaml instead)
+- ❌ Template components, shared utilities, source YAML, schemas
+
 ## Why Validation Matters
 
 - **PDF generation** depends on valid TypeScript data module

.claude/tailor-context.yaml

@@ -1,5 +1,5 @@
 # Auto-generated by /tailor command
-# Last updated: 2025-10-09T12:01:57.159Z
+# Last updated: 2025-10-15T16:49:51.673Z
 # Active company: tech-corp
 active_company: tech-corp
 company: Tech-Corp
@@ -31,4 +31,4 @@ job_details:
     - Scala
   team_context: 500+ people in product organization, cross-functional teams
   user_scale: 20 million users globally across 500 cities in 30 countries
-last_updated: '2025-10-09T12:01:57.159Z'
+last_updated: '2025-10-15T16:49:51.673Z'

.env.example

@@ -22,6 +22,27 @@ LOG_TIMESTAMPS=true
 # Only applies to 'human' format. Set to 'false' for cleaner terminal output
 LOG_EMOJI=true
 
+# =============================================================================
+# File Watcher Configuration
+# =============================================================================
+
+# Debounce delay for file watcher (milliseconds)
+# Prevents multiple rapid regenerations when saving multiple YAML files
+# - Set to 300 (default): Wait 300ms after last change before regenerating
+# - Set to 0: Process every change immediately (disables debouncing)
+# - Increase to 500-1000: Useful if you frequently save many files at once
+FILE_WATCH_DEBOUNCE_MS=300
+
+# Compact logging mode for tailor-server
+# Reduces log output to minimal essential information
+# - Set to 'false' (default): Show all detailed logs (recommended for development)
+# - Set to 'true': Show only startup message and regeneration results
+#   Compact mode output example:
+#     🚀 Tailor server ready • Watching: tech-corp • Debounce: 300ms
+#     ✅ metadata.yaml → Regenerated (1.2s)
+#     ❌ resume.yaml → Failed (validation error details shown)
+TAILOR_SERVER_COMPACT_LOGS=true
+
 # =============================================================================
 # Usage Examples
 # =============================================================================
@@ -38,4 +59,13 @@ LOG_EMOJI=true
 # Production (JSON, warnings only):
 #   LOG_FORMAT=json LOG_LEVEL=warn bun run start
 #
+# Disable file watcher debouncing:
+#   FILE_WATCH_DEBOUNCE_MS=0 bun run tailor-server
+#
+# Increase debounce for batch edits:
+#   FILE_WATCH_DEBOUNCE_MS=1000 bun run tailor-server
+#
+# Compact mode (minimal logging):
+#   TAILOR_SERVER_COMPACT_LOGS=true bun run tailor-server
+#
 # =============================================================================