What Are Jobs?
Jobs are pipeline items that encapsulate the actual work being done for a client. They serve as the central hub for tracking work execution, coordinating schedules, managing time, documenting progress, and handling all billing activities.
Key Concept: Jobs are active work in your business—they represent approved projects where you're actually performing services. Jobs connect estimates (proposals) with invoices (billing) and everything in between.
Why Use Jobs?
Jobs provide a centralized place to:
- Track active work for customers
- Manage time with built-in time tracking
- Coordinate schedules with calendar integration
- Document progress with photos and notes
- Handle billing through estimates, change orders, and invoices
- Monitor financial status of each project
- Organize service delivery from start to completion
How Jobs Work
The Job Lifecycle
Creation:
- From Accepted Estimate - Most common path, estimate approval creates job
- Standalone Creation - Create job directly with customer + name
Execution: 3. Schedule Work - Add calendar events for service appointments 4. Track Time - Start/stop time tracking as work is performed 5. Document Work - Add photos and notes throughout project 6. Manage Changes - Create change orders for scope/price adjustments
Billing: 7. Generate Invoices - Create invoices that include estimates and change orders 8. Submit to Customer - Send invoices for payment 9. Track Payments - Monitor financial status and outstanding balances
Completion: 10. Complete Job - Mark job as finished 11. Archive - Move to historical records
Creating Jobs
Creating from Accepted Estimate
Automatic Workflow:
- Customer accepts estimate online or pro accepts on their behalf
- Estimate marked as "Accepted"
- Pro clicks "Create Job" button on estimate
- System creates new job with:
- Customer relationship
- Link to accepted estimate
- Link to original lead (if estimate came from lead)
What Carries Over:
- Customer association
- Lead relationship (if applicable)
- Reference to estimate (viewable from job)
- All estimates for lead remain accessible
What Doesn't Carry Over:
- Line items (estimate serves as scope reference, not active task list)
- Pricing details (tracked through linked estimate)
- Notes or photos (these remain on lead/estimate)
Creating Standalone Job
Direct Creation:
- Navigate to Jobs section
- Create new job
- Provide customer and job name (required)
- Optionally add contact info and service address
- Job created immediately
Via Agent:
- "Create job for John Smith"
- "New job for kitchen installation"
- Agent confirms customer and name
- Job created in active status
When to Use:
- Repeat customer requesting additional work
- Small jobs not requiring formal estimate
- Emergency/urgent service calls
- Time & materials work
- No sales pipeline needed
Required vs Optional Information
Required at Creation:
- Customer - Who is the work for?
- Job Name - What is the work?
Optional (can be added later):
- Contact information (phone, email)
- Service address
- Notes
- Photos
- Schedule events
- Time tracking
Planned Enhancement:
- Customer display in job view (a future update)
- Auto-populate contact and address from customer record
- Default to customer's main address with override option
Job Information
Customer Association
Current Behavior:
- Customer is linked to job
- Customer information not displayed in job view
Planned Enhancement (a future update):
- Display customer name prominently in job view
- Link to customer detail for quick access
- Auto-populate contact info from customer
- Auto-populate address from customer's main address
- Allow override for job-specific contact/location
Contact Information
Purpose:
- How to reach customer about this specific job
- May differ from customer's main contact info
- Important for scheduling and coordination
Fields:
- Phone number(s)
- Email address(es)
- Preferred contact method
- Notes about availability
Current Process:
- Manually enter on job
- No connection to customer data
Planned (a future update):
- "Use customer contact" button to auto-populate
- Show both customer contact and job-specific contact if different
Service Address
Purpose:
- Where the work will be performed
- May differ from customer's main address
- Important for scheduling and navigation
Current Process:
- Manually enter on job
- No connection to customer data
Planned (a future update):
- Default to customer's main address
- "Use customer address" button to auto-populate
- Override if service location is different property
- Useful for customers with multiple properties
Job Status
Jobs move through various states during their lifecycle, tracked automatically based on scheduling.
Status Values
Computed Statuses (automatically updated):
-
Ready for Scheduling - Job created but no appointments scheduled yet
- User Action: Schedule the first appointment
- How it's set: Automatically when job has no schedule items
- Agent queries: "What jobs need scheduling?", "Show me unscheduled jobs"
-
Scheduled - Job has upcoming appointments
- User Action: None - show up to scheduled appointments
- How it's set: Automatically when job has any future schedule items
- Note: May also have past appointments, but as long as future appointments exist, status stays "scheduled"
- Agent queries: "What's scheduled?", "Show me scheduled jobs"
-
In Progress - Job has past appointments but no future appointments
- User Action: Either schedule another visit OR mark job as finished
- How it's set: Automatically when all schedule items are in the past
- Why this matters: This status signals the job needs attention - either more work needs to be scheduled or the job should be closed out
- Agent queries: "What jobs are in progress?", "What needs my attention?"
Manual Statuses (user sets):
-
Finished - Work complete, ready for final invoicing/closeout
- User Action: Final billing, archiving
- How it's set: User manually marks job as finished via "Close Job" action
- Agent queries: "Show me finished jobs"
-
Archived - Historical record, no longer active
- User Action: None - job is archived
- How it's set: User manually archives completed/cancelled jobs
- Agent queries: "Show me archived jobs"
Status Flow Examples
New Job Workflow:
- Create job →
ready for scheduling - Schedule first appointment →
scheduled - Appointment occurs (date passes) →
in progress - Schedule follow-up appointment →
scheduled - Final appointment occurs →
in progress - User marks as finished →
finished - User archives →
archived
Single Visit Job:
- Create job →
ready for scheduling - Schedule appointment →
scheduled - Appointment occurs →
in progress - User marks as finished →
finished
Multi-Day Project:
- Create job →
ready for scheduling - Schedule 3 days of work →
scheduled - Day 1 passes (2 more days scheduled) →
scheduled(still has future appointments) - Day 2 passes (1 more day scheduled) →
scheduled - Day 3 passes (no more appointments) →
in progress(needs to schedule more or finish) - User marks as finished →
finished
Finding Jobs That Need Attention
Agent Queries:
- "What jobs need scheduling?" → Returns
ready for scheduling+in progressjobs - "Show me scheduled work" → Returns
scheduledjobs - "What jobs are in progress?" → Returns jobs with past appointments needing attention
- "Show me finished jobs" → Returns
finishedjobs
Dashboard Filters:
- Filter by status to see jobs in each state
- "Needs Scheduling" shows jobs requiring scheduling action
- "Scheduled" shows jobs with upcoming work
- "In Progress" shows jobs needing follow-up or closure
Status Update Triggers
Status updates happen automatically when:
- Schedule appointment created → May change to
scheduled - Schedule appointment deleted → May revert to
ready for schedulingorin progress - Time passes and appointments become "past" → May change to
in progress - User manually marks job as
finishedorarchived
Note: You cannot manually change computed statuses (ready for scheduling, scheduled, in progress). These always reflect the current schedule state. Only finished and archived can be manually set.
Implementation: Status is computed by JobStatusService based on schedule timing (GitHub Issues #167, #79)
Time Tracking
Jobs include built-in time tracking to monitor hours worked.
Starting and Stopping Time
From Job View:
- Click "Start Time Tracking" button
- Timer begins running
- Click "Stop Time Tracking" when work session ends
- Time period is saved
Via Agent:
- "Start time tracking for kitchen remodel"
- "Stop time tracking"
- Agent confirms action
Features:
- Multiple time periods per job
- Compile complete history of hours worked
- Running time displayed in real-time
- No data loss if app crashes (tracking is server-side)
Time Tracking Features
Multiple Sessions:
- Track each work session separately
- Ideal for jobs spanning multiple days
- Complete timeline of when work was performed
Server-Side Tracking:
- Time tracking opens and closes on server
- No data loss if app closes or crashes
- Accurate time tracking guaranteed
Time History:
- View all tracked time periods
- See total hours worked
- Breakdown by session
- Edit or delete time entries after creation
Current Limitations:
- Time tracking is job-level only (not task-specific)
- No integration with invoicing yet
- No per-task time tracking
Planned Enhancements:
- Task-level time tracking (a future update)
- Time tracking integration with job costing (a future update)
- Automatic labor cost calculation from time tracked
- Billable vs non-billable time designation
Scheduling
Calendar Integration
Jobs integrate with the calendar system for scheduling work appointments.
Schedule Events on Jobs:
- Single job can have multiple scheduled events
- Useful for work spanning multiple sessions
- Each event appears in calendar view
- Events listed on job detail view
Creating Events:
- Via UI: Click schedule button on job
- Via Agent: "Schedule work for Tuesday at 9am"
- Specify date, time, duration
- Add event description/notes
Calendar View:
- All events (leads and jobs) visible in calendar
- Filter by event type
- Navigate by day/week/month
- Click event to view job/lead details
Crew Assignment
Current Feature:
- Crews can be assigned to jobs
- Crews are high-level categories
- Crews don't yet have members
Multi-User Future:
- Assign specific team members
- Crew composition management
- Schedule conflicts detection
- Workload balancing
Event Management
Edit/Reschedule:
- Update event date/time
- Change duration
- Modify description
- No constraints currently on changes
Notifications:
- No reminders currently implemented
Planned Enhancement (a future update):
- Reminders before events (1 day, 2 hours, 30 min)
- Push notifications when events approach
- Snooze/dismiss reminders
- Mark events complete from notification
Financial Management
Jobs serve as the central hub for all billing activities.
Estimates
Estimate Association:
- Jobs created from estimates maintain link
- View accepted estimate from job
- Single estimate can only be associated with one job
- Job can have multiple estimates (all linked via lead)
Multiple Estimates:
- If lead had multiple estimates, all are viewable from job
- Helpful for reference (customer chose Premium over Basic)
- Historical record of pricing options
Change Orders
Purpose:
- Handle scope/price changes after estimate acceptance
- Add work discovered during job
- Adjust pricing for modifications
- Track changes separately from original estimate
Usage:
- Create change orders on jobs as needed
- Any quantity of change orders per job
- Change orders have own line items and pricing
- Must be accepted by customer (same as estimates)
Invoices
Invoice Creation:
- Create invoices directly from jobs
- System prompts: Include estimate and change order line items?
- Option 1: Auto-populate from accepted estimates/change orders
- Option 2: Create custom invoice with manual line items
Smart Invoice Generation:
- System compares all estimate and change order line items
- Keys invoice items to source documents
- If invoice is draft, updates are applied
- If invoice submitted/paid, new invoice needed
- Supports negative invoices (refunds to customer)
Multiple Invoices:
- Jobs can have any quantity of invoices
- Useful for:
- Deposit invoicing
- Progress billing (partial payments)
- Final invoice
- Additional work invoices
- Refunds
Invoice Types:
- Full invoice (all estimate + change order items)
- Partial/progress invoice (percentage of work completed)
- Deposit invoice (upfront payment)
- Materials-only invoice
- Labor-only invoice
- Refund invoice (negative amount)
Via Agent (a future update):
- Planned enhancement for agent-driven invoice generation
- "Create invoice for this job"
- "Invoice that includes estimate and change orders"
- "Bill customer for completed work"
- Agent guides through smart invoice creation
Financial Status View
Job Financial Summary:
- View total financial picture of job
- Items from estimates (approved pricing)
- Items from change orders (adjustments)
- Balanced against invoiced amounts
- Outstanding balance calculation
Example:
Revenue:
Accepted Estimate: $5,000
Change Orders: $ 500
Total Revenue: $5,500
Invoiced:
Invoice #001 (Paid): $2,500
Invoice #002 (Submitted): $3,000
Total Invoiced: $5,500
Outstanding Balance: $3,000
Fully Invoiced: Yes
Paid in Full: No
Planned Enhancement (a future update):
- Full job costing and profitability tracking
- Track actual costs (labor, materials, equipment, subcontractors)
- Compare estimated revenue vs actual costs
- Calculate profit/loss per job
- Cost variance analysis
- Budget alerts for overruns
Documentation
Notes
Purpose:
- Internal job knowledge sharing
- Track important details
- Communication among team (multi-user future)
- Work progress updates
- Customer communications log
Features:
- Free-form text notes
- Add notes anytime during job
- Edit/delete notes
- Chronological list
- Search within notes
Use Cases:
- Customer preferences and requests
- Site access information
- Material specifications
- Work completed each session
- Issues discovered
- Follow-up items
Photos
Job Photos:
- Document work in progress
- Completion photos
- Before/after comparisons
- Problem areas discovered
- Materials used
Features:
- Take photos directly in app
- Upload from device
- Add title and description
- Organize chronologically
- View in grid or list
Planned Enhancement (a future update):
- Tabbed Photo Interface:
- Job Photos tab (current)
- Lead Photos tab (from original site visit)
- All Photos tab (combined chronological view)
- Benefits:
- Complete project documentation in one place
- Before/after comparison (lead photos vs completion)
- Reference initial conditions during work
- Comprehensive project history
Invoice Integration (a future update):
- Attach photos to invoices
- Show customers work completed
- Before/after documentation
- Visual proof of value
- Reduce payment disputes
Tasks and Checklists
Current Status:
- Task lists not yet implemented
Planned Enhancement (a future update):
Job Task Lists:
- Break down work into manageable tasks
- Track completion progress
- Check off tasks as completed
- Reorder tasks
- Assign to crew members (multi-user)
- Link to estimate line items
- Task completion percentage for job
- Time tracking per task (future)
Dynamic Task Management:
- Agent-generated task lists
- "Hey agent, create task list of things I need to do today"
- Agent analyzes pending work and generates priorities
- Personal task inbox separate from job tasks
- Cross-domain task tracking
Benefits:
- Better job organization
- Track completion progress
- Nothing falls through cracks
- Team coordination (multi-user)
- Personal productivity
Agent Capabilities
The Job Agent supports comprehensive natural language interactions:
Search and Find
Examples:
- "Find jobs for John Smith"
- "Show me active jobs"
- "Jobs scheduled this week"
- "Find jobs with outstanding invoices"
- "Which jobs are completed?"
Agent Behavior:
- Flexible natural language understanding
- Searches across customer names, dates, status
- Returns relevant matches
- Offers to provide more details
Create Operations
Examples:
- "Create job for John Smith"
- "New job for bathroom remodel"
- "Add job for ABC Company"
Agent Workflow:
- Confirms or prompts for customer
- Asks for job name
- Creates job immediately
- Guides through additional setup if needed
Time Tracking
Examples:
- "Start time tracking"
- "Stop time tracking"
- "How many hours on this job?"
- "Show me time tracking history"
Agent Actions:
- Starts/stops timer on current job
- Reports total hours tracked
- Shows time entry history
Scheduling
Examples:
- "Schedule work for tomorrow at 10am"
- "Add appointment Tuesday morning"
- "When is this job scheduled?"
Agent Actions:
- Creates calendar events
- Links to current job
- Confirms scheduling details
Updates
Examples:
- "Update job name to Kitchen Renovation"
- "Change service address"
- "Add note about customer preferences"
Agent Behavior:
- Makes requested modifications
- Confirms changes
- Updates job record
Reports and Analysis
Dashboard Integration:
- "What jobs are in progress?"
- "Show me jobs scheduled this week"
- "Jobs with outstanding invoices"
- "How many jobs are completed this month?"
Agent Provides:
- Summary of job pipeline
- Key metrics and counts
- Status breakdown
- Financial summaries
- Insights into business activity
Best Practices
Job Organization
Naming Convention:
- Use descriptive, specific names
- Include customer name and project type
- Examples: "Smith Kitchen Remodel", "ABC Corp Parking Lot Paving"
- Helps with searching and reporting
Status Management:
- Keep status current
- Update as work progresses
- Use status to filter and prioritize
- Don't leave jobs in wrong status
Documentation:
- Add notes throughout project
- Take photos at key milestones
- Document before starting, during work, at completion
- Capture issues and resolutions
- Better documentation = better customer service
Time Tracking
Accuracy:
- Start timer when work begins
- Stop timer when work ends or taking break
- Don't forget to stop timer at end of day
- Edit entries if you forgot to stop
Consistency:
- Track time for every job
- Build habit of starting/stopping
- Accurate time = better job costing (future)
- Historical data improves estimates
Multiple Sessions:
- Track each work session separately
- Don't combine multiple days into one entry
- Provides accurate timeline
- Better for billing and analysis
Financial Management
Invoice Timing:
- Invoice promptly after work completion
- Don't wait weeks to bill
- Consider progress billing for large jobs
- Faster invoicing = faster payment
Include Estimates/Change Orders:
- Use smart invoice generation
- Include all accepted estimates and change orders
- Ensures nothing is missed
- Maintains consistency with proposals
Track Outstanding Balances:
- Monitor which jobs have unpaid invoices
- Follow up on overdue payments
- Keep financial status current
- Don't let receivables age
Communication
Customer Contact:
- Keep contact info current on job
- Update if customer changes phone/email
- Note preferred contact method and times
- Improves scheduling and coordination
Notes for Team:
- Document important details
- Site access codes/instructions
- Customer preferences
- Material specifications
- Helps team (now and future multi-user)
Photo Documentation:
- Take photos before starting
- Document work in progress
- Completion photos
- Problem areas discovered
- Photos tell the story
Common Questions
Q: Can I create a job without an estimate? A: Yes. Jobs can be created standalone with just a customer and job name. This is useful for repeat customers, small jobs, or emergency work that doesn't need formal estimates.
Q: When a job is created from an estimate, what information carries over? A: The customer relationship and a reference to the accepted estimate. The job can view the estimate for scope reference. Line items are not copied—jobs don't duplicate the estimate details but link to them.
Q: Can a job have multiple estimates? A: A job can reference multiple estimates if they came from the same lead. However, an estimate can only be associated with one job. If a lead had 3 estimates and one was accepted, all 3 estimates remain viewable from the job for reference.
Q: How does time tracking work if the app crashes? A: Time tracking is server-side, so no data is lost if the app crashes or closes. The timer continues on the server and can be stopped when you reopen the app.
Q: Can I edit or delete time entries? A: Yes. Time entries can be edited or deleted after creation. This is useful if you forget to stop the timer or need to correct an entry.
Q: Can time tracking be linked to invoicing? A: Not currently, but this is planned as part of job costing features (a future update). Future enhancements will automatically calculate labor costs from time tracked and integrate with invoicing.
Q: What's the best way to handle recurring work? A: This is still being designed. Options include: (1) Create a new job each time and mark complete, or (2) Have a long-running job with multiple schedule events and invoices. Guidance will be clearer as the feature evolves.
Q: Can a completed job be reopened? A: It's recommended to create a new job for additional work rather than reopening a completed job. This maintains cleaner records and better tracking of separate work efforts.
Q: Can jobs be deleted? A: Jobs can be deleted if they have no activity (no time tracking, invoices, etc.). Rules are being reviewed. Generally, it's better to mark jobs as cancelled rather than delete them for historical records.
Q: How do I create an invoice that includes the estimate? A: When creating an invoice from a job, the system prompts whether to include estimate and change order line items. Say yes, and the system auto-populates the invoice with all accepted pricing. Alternatively, use the agent (planned) to say "create invoice that includes estimate and change orders."
Q: Can I invoice a job before all work is completed? A: Yes. Progress invoicing is supported. You can create multiple invoices for the same job—for example, a deposit invoice, a progress invoice at 50%, and a final invoice at completion.
Q: What happens if I need to add work that wasn't in the estimate? A: Create a change order on the job. The change order has its own line items and pricing. When creating invoices, the system can include both estimate and change order items automatically.
Q: Can I refund a customer through an invoice? A: Yes. Invoices can be negative amounts (refunds to customer). This would be handled through the invoice system linked to the job.
Q: How do I see the total financial status of a job? A: The job view shows a financial summary with total revenue (estimates + change orders) balanced against invoiced amounts. You can see outstanding balances and payment status.
Q: Can I assign crews or team members to jobs? A: Crews can be assigned to jobs currently, but crews don't yet have members. Multi-user features will introduce team member assignment, workload balancing, and coordination.
Q: Are there notifications for scheduled job events? A: Not currently, but this is planned (a future update). Future enhancements will include reminders before events, push notifications, and the ability to mark events complete from notifications.
Q: Can I see photos from the original lead when viewing a job? A: Not currently, but this is planned (a future update). A tabbed interface will show job photos, lead photos, and a combined view for complete project documentation.
Q: Can I attach photos to invoices to show customers the work? A: Not currently, but this is planned (a future update). Future enhancement will allow selecting photos from the job to include in customer invoice view for before/after documentation and value demonstration.
Q: Can the agent help create invoices? A: Not directly yet, but this is planned (a future update). The agent will be able to generate invoices from jobs with natural language commands like "create invoice that includes estimate and change orders."
Q: Is there a history of changes made to jobs? A: Not currently, but this is planned for multi-user environments (a future update). Job history will track all changes, who made them, and when—important for team coordination and accountability.
Q: Can I track actual costs vs estimated pricing? A: Not currently, but comprehensive job costing is planned (a future update). This will track labor, materials, equipment, and other costs to calculate true profitability per job.
Q: Can I create task lists for jobs? A: Not currently, but this is planned (a future update). Task lists will help break down work, track completion, and coordinate team efforts. The agent will also generate dynamic task lists.
Q: How are job statuses determined? A: Currently status changes are tied to actions like scheduling events. Status logic is being reevaluated and improved (a future update) to provide clearer workflow, validation rules, and automatic transitions.
Q: Can I see the customer name in the job view? A: Not currently prominently, but this is being added (a future update). Enhancement will display customer name, link to customer detail, and allow auto-populating contact and address from customer record.
Q: Can the agent search for jobs? A: Yes. The job agent supports comprehensive natural language search. Ask things like "find jobs for John Smith" or "show me active jobs" and the agent will search across all job data.
Q: Can jobs be created from the dashboard? A: Yes. Use the job agent from the dashboard with natural language commands like "create job for John Smith." The agent guides you through the process.
Tips for Success
Efficient Job Management
Start Right:
- Create from accepted estimate when possible (maintains traceability)
- Enter complete information upfront (reduces back-and-forth)
- Set clear job name for easy searching
Stay Organized:
- Update status as work progresses
- Keep notes current
- Take photos at key milestones
- Track time consistently
Finish Strong:
- Complete all work before marking done
- Invoice promptly
- Document completion
- Archive completed jobs periodically
Time Tracking Habits
Build Routine:
- Start timer when arriving at job site
- Stop timer when leaving or taking break
- Review time entries at end of day
- Correct any forgotten stops
Be Accurate:
- Track actual work time, not drive time (unless billing for it)
- Separate work sessions by day
- Note what was accomplished in descriptions
- Historical data improves future estimates
Documentation Excellence
Photo Strategy:
- Before photos: Initial conditions, problem areas
- During photos: Work in progress, installations
- After photos: Completed work, quality details
- Problem photos: Issues discovered, damage, wear
Note Taking:
- Customer requests and preferences
- Site access information
- Material specifications used
- Work completed each session
- Follow-up items needed
- Customer communications
Financial Best Practices
Invoice Management:
- Review estimate and change orders before invoicing
- Use smart invoice generation (include estimates/change orders)
- Invoice in stages for large jobs (deposit, progress, final)
- Follow up on unpaid invoices promptly
Change Order Discipline:
- Create change orders for any scope changes
- Get customer approval before extra work
- Document why change was needed
- Keep pricing transparent
Monitor Job Finances:
- Check financial status view regularly
- Track which jobs have outstanding invoices
- Identify jobs with payment issues early
- Understand total revenue vs invoiced amounts
Related Features
Estimates:
- Jobs created from accepted estimates
- Estimate serves as scope/pricing reference
- Multiple estimates viewable from job
- See: Estimates Overview
Invoices:
- Generate invoices from jobs
- Include estimate and change order items
- Progress and partial billing
- See: Invoices Overview
Change Orders:
- Handle scope/price changes
- Add work discovered during job
- Track modifications separately
- See: Change Orders Overview
Leads:
- Jobs may originate from leads
- Lead photos accessible from job (planned)
- Complete pipeline tracking
- See: Leads Overview
Customers:
- Every job requires a customer
- Customer contact and address (planned auto-populate)
- Track all work for each customer
- See: Customers Overview
Time Tracking:
- Built into jobs
- Track work sessions
- Calculate total hours
- Future job costing integration
Scheduling:
- Calendar integration
- Multiple events per job
- Crew assignment
- See: Scheduling Overview
Summary
Jobs are the central hub for active work delivery in HomeGuild:
- Create from accepted estimates or standalone for direct work
- Track time with built-in start/stop tracking for each work session
- Schedule work with calendar integration and multiple events
- Document progress with photos and notes throughout the project
- Manage billing through linked estimates, change orders, and invoices
- Monitor financials with complete revenue and invoicing status
- Coordinate delivery from start to completion with status tracking
Use the Job Agent for fast, natural language interactions, or work through the UI for detailed control. Jobs keep all your active work organized and connected to the complete billing cycle.