Human resources company using ShipifyAI

ShipifyAI was originally designed for software teams, but the same workflow maps cleanly onto any organisation that produces text artefacts in a versioned repository, has a board of work items, and announces results on a chat channel. An HR or People Operations department fits the model well. Policies, employee handbooks, job descriptions, performance review templates, onboarding documents, and internal communications are textual artefacts that benefit from version control, peer review, and an explicit record of changes. HR work also benefits from an AI assistant that has been told exactly which labour-law sources to consult and exactly which terminology to use across a multi-jurisdictional workforce. This article walks through the setup of ShipifyAI for a fictional mid-sized HR department. It covers how to structure the Jira board, the document repository, and the Slack channel, how to write a `CLAUDE.md` tailored for HR drafting, and which MCP servers to allow so that the AI can produce policies and templates while keeping individual employee information firmly out of scope.

The scenario

The department serves a company of roughly three hundred employees across two countries. There is an HR director who owns the function, two HR business partners who handle policy and employee relations, a recruiter who owns hiring documentation, and a learning and development specialist who handles onboarding and training materials. The company has employees in both jurisdictions, so every policy needs a localised version, and every job description follows the company's internal job architecture. The HR director wants to use AI to accelerate routine drafting of policies, job descriptions, and onboarding materials, while keeping HRBPs and external counsel in the review seat for anything legally sensitive. Individual employee matters never touch the AI.

ShipifyAI's role is to take a structured task from Jira, hand it to Claude with the company's job architecture and the relevant labour-law context, produce a draft document committed to the repository, open a pull request for HRBP review, and post the link in Slack. Nothing reaches employees without an HRBP or director signing off, and anything with legal exposure is reviewed by external counsel before publication.

Setting up the document repository

The department uses GitHub as its document repository, with private access restricted to the HR team and read-only access for the leadership team. The repository is structured to mirror the function. There is a `policies` directory containing the canonical company policies, organised by topic such as leave, conduct, performance, and remote work, with one file per topic and per jurisdiction. There is a `handbook` directory containing the employee handbook, assembled from the policies into a single reader-friendly document. There is a `job-descriptions` directory organised by department and by level, with one file per role. There is an `onboarding` directory containing onboarding programme materials, organised by function. There is a `comms-templates` directory containing internal communications templates such as offer letter wrappers, manager update templates, and announcement boilerplate. Every Markdown file uses YAML front matter for metadata such as jurisdiction, effective date, owner, and last legal review date.

The ShipifyAI CLI writes its drafts as Markdown — that is the format the agent emits to the branch, because plain-text diffs make pull request review meaningful, branches stay tidy, and the AI can produce changes the same way it produces code. What the department does with that Markdown once an HR reviewer has signed off is the department's own call, and outside ShipifyAI's scope. The example company in this article renders the handbook into a PDF through a CI pipeline using its house template, runs a lint that validates front matter, and runs a forbidden-terms check that flags discriminatory language, outdated legal terminology, and any string that resembles personally identifiable information — but a different department that ships its policies into a dedicated HRIS or document management system would not have to change anything about the way ShipifyAI operates.

A useful comparison with the other scenarios clarifies where the HR scenario sits on the merge spectrum. The HR scenario is closer to the law firm scenario in legal sensitivity and to the family-book scenario in that the canonical handbook lives on the default branch and merges are a regular, expected outcome. A new or updated policy that has been through HRBP review and external counsel sign-off is merged into the default branch and becomes the active version of that policy. Pull requests are both a review surface and a path to merge. They are not, as in the law firm or agency scenarios, simply a delivery channel from which a draft is exported elsewhere.

The default branch requires a pull request and at least one approval from the HR director before merging, and required status checks include the lint, the forbidden-terms check, and an inclusive-language pass. External counsel review happens out of band: counsel reviews the rendered PDF and emails sign-off back to the HRBP, who then merges the pull request. Direct pushes to the default branch are forbidden through branch protection.

The GitHub Personal Access Token used by the worker follows exactly the same rules as in the software scenario. It is a fine-grained token, scoped to this single repository, with Read and write permissions on Contents and Pull requests, Read-only on Metadata, and no Administration permission. The worker can therefore push feature branches and open pull requests, but it cannot bypass branch protection on the default branch and it cannot merge anything itself.

Setting up the Jira board

The Jira project mirrors the HR function. Each issue represents a unit of work, such as drafting a new policy, localising an existing policy for the other jurisdiction, writing a job description for a new role, refreshing an onboarding module, or producing a communications template for a recurring scenario.

The board has four columns that match the ShipifyAI model. The source column, named "Ready for AI drafting", holds tasks that have been screened by an HRBP and are deemed appropriate for AI drafting. The In Progress column holds tasks the AI is currently working on. The In Review column, renamed "Ready for HRBP review", holds tasks where the AI has produced a draft on a feature branch and a pull request has been opened. From this column an HRBP picks up the draft. The Incomplete column holds tasks the AI returned because the brief was insufficient or because the matter required human judgement, often legal judgement, before drafting could begin.

The board has a fifth column, "Backlog", which is not visible to the AI. The HRBP or director lands every new task there. Each task is reviewed before it moves to the AI column, and this intake step is the department's strongest safety gate. Anything individual-employee-specific is absolutely never moved to the AI column. Performance management for a specific person, disciplinary proceedings, accommodation requests, parental leave specifics for a named employee, termination paperwork, compensation discussions, and any matter involving an active grievance stays entirely with HRBPs and external counsel. The AI works only on policy, template, and general material that applies to classes of employees rather than to individuals.

The minimum wait time on the project is set to a full business day. HR drafting rarely has the kind of hourly urgency that newsrooms or marketing campaigns have, and the day-long buffer gives an HRBP the opportunity to claim a task they want to handle personally.

Setting up the Slack channel

The company uses Slack for internal communication. A dedicated channel, `#hr-ai`, is configured as the project's notification channel in ShipifyAI. The channel is restricted to the HR team. Notifications it receives include the announcement that a draft is ready for review, with a link to the pull request that holds it, and the announcement that the AI was unable to complete a task and the reason why. The link in the notification is the HRBP's entry point: they click through, read the diff, and take the work from there.

The Slack Bot Token is generated and configured exactly as described in the worker configuration article, with the same four scopes. The bot is invited explicitly to `#hr-ai` and to no other channel. It is never, under any circumstance, invited to a general employee channel, a manager channel, or any channel where individual employee matters might be discussed. This is reinforced by an explicit reminder in the channel topic.

Writing a CLAUDE.md for the HR context

The `CLAUDE.md` file is where the department's conventions are taught to the AI. It is the most important file in the repository for the quality of the drafts produced, and it is worth investing time in.

The file opens with a project overview that explains the company, the jurisdictions in which it operates, the size of the workforce, and the function of the HR department. It explains the principal categories of artefact the repository holds and who reads them. The AI then knows that "the policy" refers to a specific company policy, that "the jurisdiction" implies a specific national labour-law context, and that drafts must be in the language of that jurisdiction.

The file describes the structure of the repository, naming the policies directory, the handbook, the job descriptions, the onboarding materials, and the communications templates. It tells the AI that policy changes propagate to the handbook only through deliberate assembly into the canonical handbook document, so a policy edit must never silently change the handbook copy.

The file describes the department's house style. Tone is clear, neutral, and inclusive. Reading-level targets favour plain language for employee-facing material. Policies follow a strict structure of purpose, scope, definitions, policy, procedure, exceptions, and effective date. Job descriptions follow the company's job architecture, drawing role descriptions from the canonical levels and bands. The file lists inclusive-language rules, jurisdiction-specific legal callouts such as which provisions of the local labour code must always be referenced explicitly, and the company's discipline around naming legal entities and groups of employees.

The file also lists what the AI must never do. It must never draft anything that could be read as legal advice to an individual employee. It must never produce a document about a specific named person. It must never include personally identifiable information. It must never invent a statutory reference or quote a provision it has not retrieved through one of the allowed MCP servers. It must never make claims about benefits, leave entitlements, or termination procedures without flagging the draft for legal review. It must never bypass the review gate by trying to push directly to the default branch.

The file ends with a checks section. Before considering a task complete the AI must run the department's lint script, which validates front matter and checks for forbidden terms and personally identifiable information. It must run the inclusive-language pass. It must verify every statutory reference by querying the appropriate labour-law MCP server. It must produce a summary of the change in the pull request body, written for the reviewing HRBP, listing every statutory citation and explicitly flagging any clause that requires external counsel review.

Allowed MCP servers for HR drafting

This is where the HR scenario diverges from the software scenario. The AI in an HR context needs structured access to labour law in the company's jurisdictions, to the company's job architecture, and to its canonical policies, and it must not be allowed to reach any source of individual employee data.

The department enables a small, curated set of MCP servers on the worker machine, configured in `~/.claude/mcp.json`. The list is intentionally narrow.

- A labour-law MCP server, connected to the official electronic gazette of each jurisdiction the company operates in. The server exposes search of the consolidated text of labour-code provisions by reference and fetch by article number, plus access to vetted secondary sources such as official commentaries. The AI is instructed to cite by official reference, to include the consolidation date, and to flag any provision that has been amended within the last year.

- A policy MCP server, scoped to the `policies` directory of the repository. The server exposes structured search across the company's canonical policies so the AI can locate the current policy on a topic before drafting an update or a localisation.

- A job-architecture MCP server, scoped to the company's level and band definitions and competency framework, held in a controlled subdirectory of the repository. The server exposes lookup by level, by band, and by competency so that job descriptions stay consistent with the architecture.

- A handbook MCP server, scoped to the assembled employee handbook so that draft policies can be checked against the language already used in the handbook for consistency.

- A filesystem MCP server, scoped to the working directory of the repository. This is the same MCP recommended in the software scenario.

The department explicitly does not connect MCP servers that would expose individual employee data or that could allow the AI to fabricate legal authority. There is no MCP server connected to the HRIS, the payroll system, the applicant tracking system, the benefits administration platform, the performance management system, or the time-tracking system. Individual employee data lives in those systems and is handled by HRBPs through the systems' own interfaces, never through the AI. There is no MCP server connected to the company email or calendar. There is no MCP server that can fetch arbitrary URLs from the open internet, because outdated legal information posted on third-party sites is a particularly dangerous source for HR work.

The MCP configuration file lists the chosen servers under `mcpServers`, naming each one and specifying the command that runs it. Each server runs as a child process of Claude Code on the worker machine, with its own credentials managed inside the server itself. The credentials of the labour-law server live in environment variables on the worker, separate from any other secret, and the department rotates them on the same schedule as the GitHub PAT.

Skills for HR drafting

The department ships its own skill pack inside `.claude/skills`, parallel to the software scenario but tailored for HR work.

A `draft-job-description` skill describes the company's preferred structure for a role description, including purpose, scope, key responsibilities, required competencies aligned with the job architecture, and qualifications. The skill instructs the AI to draw responsibilities and competencies from the job architecture MCP rather than inventing them, and to comply with the jurisdiction's salary-disclosure rules where applicable, including a clear advertised salary range where required.

A `draft-policy` skill describes the strict structure of a policy in the department's house style: purpose, scope, definitions, policy, procedure, exceptions, effective date. The skill instructs the AI to consult the existing policy on the topic before drafting an update and to cite every statutory reference through the labour-law MCP.

A `localise-policy` skill describes how to take a policy written for one jurisdiction and produce a localised version for another. The skill instructs the AI to retrieve the parallel labour-law provisions for the target jurisdiction, to map each clause of the source policy to the target jurisdiction's framework, and to flag every clause that needs counsel review with an explicit note in the draft.

An `inclusive-language-pass` skill is a dedicated pass that re-reads a draft against the department's inclusive-language rules. The skill is useful both as a step inside other skills and as a standalone task when an HRBP wants to refresh older material.

A `self-review-hr` skill mirrors the software self-review skill but adapted for HR artefacts. It is the strictest review skill in the pack. It instructs the AI to re-read the draft as a sceptical legal reviewer, to check that no passage could be read as individual legal advice, to verify that every statutory reference exists, to confirm that no personally identifiable information has slipped in, to verify that no individual employee is named, and to flag every clause that requires external counsel review before publication.

Iterating with the AI through review comments

The HRBP is not limited to taking the first draft as-is. The same PR review follow-up loop that the software workflow uses is available in the HR scenario, and it is the natural way to push corrections back to the AI without rewriting the draft by hand.

Every pull request opened by the worker has a title that starts with `[AI GENERATED]`. As long as that prefix is in the title, the AI will keep watching the pull request and will respond to review comments on it. The HRBP writes a review comment on the relevant line or paragraph. The comment can ask for a different formulation, a softer or firmer tone, a missing exception, an additional statutory citation, a clarification of scope, or any other concrete change.

Six hours after the comment is posted, the worker treats the thread as actionable, posts a thumbs-up reaction as an acknowledgement that work has started, and asks Claude to address the comment in the context of the current branch. If Claude makes the change it commits the edit to the same feature branch with a message starting `[AI GENERATED] address review comment`, pushes the branch, and replies on the thread with `done [AI GENERATED]`. If Claude judges the comment incorrect or out of scope, it replies with `[AI GENERATED] declining` and a one-sentence reason, and leaves the text unchanged.

The six-hour minimum delay exists deliberately so that quick HRBP-to-HRBP clarifications do not trigger AI responses. External counsel review happens out of band on the rendered PDF rather than through PR comments, because counsel work is billed and tracked outside the repository.

This loop is what makes routine policy work practical. The HRBP does not need to perfect every draft by hand. They can hand back specific corrections, get a revised version a few hours later, route it to counsel for sign-off, and then merge it into the canonical handbook.

Security and confidentiality

The four pillars of ShipifyAI's security model apply to the HR scenario as they do to the software scenario, with a few HR-specific reinforcements that follow from the sensitivity of the function.

Employee privacy is paramount, and the repository is configured to make it structurally hard to violate. No personally identifiable information ever enters the repository. No compensation data for a specific individual ever enters the repository. No performance data for a specific individual ever enters the repository. The HRIS, the payroll system, and the applicant tracking system hold individual data, and they are accessed by HRBPs directly through those systems' own interfaces and audit trails. The AI sees only general-purpose policy and template material that applies to classes of employees, never to individuals.

The worker runs on a dedicated, isolated machine. The department can choose per-jurisdiction worker isolation if local data protection rules favour it, so that material concerning one jurisdiction is processed only on a worker placed in that jurisdiction. The worker machine has no email client, no HRIS credentials, no payroll credentials, no access to billing or time-tracking systems. The AI sees only the repository it is working on and the MCP servers explicitly listed in the configuration.

The AI does not modify Jira directly. The HRBP's intake decisions are the department's primary safety gate, and the worker only ever sees tasks that have been approved into the source column.

The AI cannot push to the default branch. Every change reaches the canonical handbook through a pull request, an HRBP review, external counsel sign-off where applicable, and a deliberate merge by the HR director. The PAT scope refuses direct pushes to the default branch, the deny list in the Claude settings refuses it, the CLI's branching logic does not produce such pushes, and the branch protection rule on the GitHub side would reject the operation.

In addition to the standard four pillars, the department enables an egress firewall on the worker machine that allows outbound traffic only to the GitHub API, the ShipifyAI backend, the Anthropic API, the Slack API, and the specific endpoints of the labour-law and policy MCP servers. The AI cannot reach the open internet from the worker, so it cannot exfiltrate policy drafts and it cannot cite outdated legal information from third-party sites. The department also enables read-only mounts for everything outside the project working directory and rotates the worker container daily.

A typical task end-to-end

Consider how a single task flows through this setup. The company has decided to update its parental leave policy to align with a recent amendment in one jurisdiction, and the same policy needs to be localised for the second jurisdiction. An HRBP creates a Jira issue titled "Localise parental leave policy for jurisdiction B following amendment to jurisdiction A statute", references the amended labour-code provision, and lands the task in Backlog. The HRBP reviews the issue, judges it appropriate for AI drafting, adds the necessary context, and moves it to "Ready for AI drafting". The minimum wait time of a full business day ticks down.

The next morning the worker picks up the task. Claude reads `CLAUDE.md`, loads the policy and localisation skills, retrieves the canonical parental leave policy from the policy MCP, retrieves the relevant labour-code provisions for jurisdiction B through the labour-law MCP, retrieves the parallel provisions in jurisdiction A for cross-reference, and produces a feature branch with a localised draft of the policy. Each clause is mapped to the jurisdiction B framework. Two clauses are flagged as needing external counsel review with explicit notes. The AI then runs the lint script, runs the inclusive-language-pass skill, runs the self-review-hr skill, and opens a pull request titled "[AI GENERATED] Localise parental leave policy for jurisdiction B". The pull request body summarises the change, lists every statutory citation, names the two clauses flagged for counsel, and notes the effective date once the amendment takes effect. The Slack bot posts the link to `#hr-ai` and the Jira task moves to "Ready for HRBP review".

The HRBP opens the pull request, reads the diff alongside the cited labour code, leaves three review comments asking for tonal adjustments and a sharper exceptions clause. Six hours later the worker addresses the threads, makes the changes, replies `done [AI GENERATED]` on each, and pushes the revised text. The HRBP exports the rendered PDF and sends it to external counsel. Counsel returns sign-off with a small wording change on one of the flagged clauses, the HRBP applies it directly in a follow-up commit on the same branch, the HR director reviews and approves the pull request, and the policy is merged into the default branch. The canonical handbook is reassembled by the CI pipeline and the new version is published to employees through the company's normal communications channels.

The Jira task moves to Done the moment the pull request is merged. The Slack channel announces the completion. The canonical handbook now reflects the localised parental leave policy.

At every step a human controls the gate. The HRBP decides what the AI works on. The HRBP reviews the draft, external counsel signs off on legal sensitivity, the director approves the merge, and only general-purpose policy work touches the AI. Individual employee matters stay entirely with HRBPs through the HRIS, where they belong.

Where to go next

The worker configuration article explains how to obtain and install each integration token in detail. The Claude configuration article explains how to write `CLAUDE.md`, how to author skills, and how to configure the allowList. The control article explains how an HRBP takes a draft or a task back from the AI at any point. The security article explains the four pillars in depth, including the rationale behind each layer of defence.