AI Agent

This document defines the supervised AI Agent for the Headkount build phase.

The AI Agent helps a User understand records and prepare changes. It does not replace the User, the application rules, or the Schedule Optimizer.

Responsibilities

Component	Responsibility
User	Gives the request and approves or rejects each proposed change.
AI Agent	Reads current records and converts the request into a typed proposal.
Application command	Validates access, input, approval, and business rules.
Schedule Optimizer	Creates deterministic Schedule Versions from structured inputs.
Postgres	Stores the approved result and its activity history.

The AI Agent has no approval authority. It receives the same access as the signed-in User.

Agent flow

User request
     |
     v
Current page, filters, and selected records
     |
     v
AI Agent reads current Headkount data
     |
     v
Typed proposal with effect and reason
     |
     v
User approves or rejects
     |
     v
Application command validates and writes
     |
     v
Postgres -> Electric Sync -> Updated interface

The Agent reloads required records before it proposes a change. An old chat message never becomes the current business record.

Agent tools

Tool group	Agent action	Approval
Workspace tools	Read the current page, filters, selected records, and visible Schedule Version.	Not required
People tools	Read beauty educator profiles, availability, work limits, and eligibility.	Not required
Business tools	Read Brands, Contracts, requirements, Markets, Doors, and source state.	Not required
Schedule tools	Read assignments, gaps, warnings, reasons, and approval state.	Not required
Profile tools	Propose a profile, capacity, availability, or eligibility change.	Required
Schedule instruction tools	Propose an exclusion, preference, Assignment Lock, or allowed exception.	Required
Generation tools	Request a new deterministic Schedule Version.	Required
Operations tools	Propose a ticket update or a manual operating action.	Required

The launch version does not give the AI Agent a retailer booking tool, Connecteam publishing tool, cancellation tool, or Schedule approval tool.

Schedule requests

The Agent converts a schedule request into structured Scheduling Instructions. It does not edit Schedule cards or Schedule JSON directly.

The Schedule Optimizer applies the instructions and creates a new Schedule Version. The Agent then explains the new result.

If a request breaks a required rule, the Agent names the rule. The Agent also shows all valid alternatives.

The Agent cannot create contracted work from free text. An authorized User creates or approves each Contract and requirement.

Approval

Every write uses the same approval flow.

1. The Agent shows the exact proposed change.
2. The Agent shows the affected record, current value, new value, and reason.
3. The User approves or rejects the proposal.
4. A rejected proposal makes no change.
5. An approved proposal enters the typed command path.
6. The command validates the current record and User access again.
7. The Agent reports the committed result after Postgres accepts it.

The Agent does not retry a rejected proposal. A data conflict makes the Agent reload the record before it creates another proposal.

Undo and correction

Undo does not erase history.

A Schedule correction creates a new Schedule Version from an earlier version or a new instruction. The prior version remains unchanged.

A profile correction uses a new approved command that restores the prior value. The activity history keeps both changes.

An external retailer action does not use automatic undo. Staff use the approved retailer process for cancellations and other external corrections.

Context

The Agent receives only the context that it needs for the current request.

Context	Content
User context	User identity, role, and access scope
Page context	Current route, filters, selected records, and visible version
Business context	Current Headkount records loaded through read tools
Rule context	Required rules, allowed exceptions, and command contracts
Conversation context	The current request and recent explanations

The Agent treats business records as the source of truth. It treats conversation text as a request, not as evidence.

Guardrails

• The Agent cannot write directly to Postgres.
• The Agent cannot call an unapproved external system action.
• The Agent cannot grant itself or a User more access.
• The Agent cannot approve a Schedule Version.
• The Agent cannot change required scheduling rules.
• The Agent cannot edit immutable Schedule Versions.
• The Agent uses stable record identifiers in every proposal.
• The application validates every proposal with deterministic code.
• A tool error stops the related action and shows the error.
• A rejected action remains rejected.

Activity history

Each Agent run records these facts:

• The requesting User
• The page and selected record context
• The User request
• Each tool name and input
• Each tool result or error
• Each approval request and decision
• Each application command and Postgres transaction
• The final Agent response

The history connects every Agent statement about a change to the command that produced the change.

Automation policy

The launch version requires User approval for every write.

Headkount can add limited automatic actions after launch through a separate written policy. The policy must name the action, scope, limits, and owner.

This Blueprint does not grant automatic approval for any action.

Result

This design gives Headkount an AI assistant that can explain data and prepare safe changes without owning business decisions.