PE Portfolio Automation Agents

PE PORTFOLIO AUTOMATION AGENTS: SHARED RULES
Every unit in this pack follows this file. The rules are written here once, and the units do not repeat them.

1. WHERE TO RUN IT
| Your situation | Use |
|---|---|
| One portfolio company, scored from interview notes | Claude app, a private Project. Chat is fine here. |
| A folder of portco files, exports and workflow notes | Claude Code, opened in that folder. |
| Portco data that must stay on a fund machine | Claude Code on that machine. |
| Building agent files, testing them, running them every month | Claude Code. Agent files only load in Claude Code. |
Model: select Claude Opus 5.5 in the model picker. Use Claude Sonnet 5 only for the first bulk read of a large export folder.
Privacy: portfolio data goes only to your own Claude account, never to us. Use a Team or Enterprise plan, or turn model training off, before any real portco file goes in. Your fund's policy on AI tools comes first, and so does each portco's.

2. BEFORE THE FIRST RUN
Ask the human for these, one at a time: {{FUND}}, {{PORTCOS}} (the company list, sector and size), {{RATES}} (the loaded cost per hour by role at each portco; default: none, ASSUMED rates must be labelled), {{MIN_VALUE}} (the smallest monthly value worth an agent; default 500 dollars a month, ASSUMED), and the named person who signs off (the operating partner or the portco CFO; default: the operating partner, ASSUMED).
First ask: "Which portfolio company, and which part of its work, is costing you the most time or money right now?" Record the answer at the top of every output.
A missing item gets a plain default, labelled ASSUMED.

3. STOP RATHER THAN GUESS
- A file path or a folder listing pasted into chat: this is a Claude Code job. Say so and stop.
- A truncated export, or a workflow note with no owner: name it and do not score it.
- A figure needs something you do not have (the hours, the volume, confirmation from IT that the data can be read): ask once, name it, mark it OPEN.
A stop blocks only the outputs that need the missing input. Everything else still runs.

4. LABELS ON EVERY FIGURE
REPORTED (who said it, document and page) · CALCULATED (show the arithmetic) · ASSUMED (who set it) · MARKETING (a vendor claim or a "saves 80 percent" line in a deck: it makes a question, never a number) · NOT IN SOURCE.
Hours and volumes from a manager interview are REPORTED, with the person's role. They are estimates, and the map says so.

5. THREE FLAG TAGS
- CHANGES THE DECISION: changes what gets built first, or blocks an agent from going live (a failed test, no data access, a workflow that must stay human).
- WORTH A QUESTION: only if the answer could move a workflow's monthly value by more than 20 percent, or move it across {{MIN_VALUE}}.
- EXPLAINED BY CONTEXT: one line under "Checked, normal". Once closed, it stays closed.
Test every flag against the list below before you raise it.

6. LOOKS WRONG, IS NORMAL
| Pattern | Why it is normal | When it is not |
|---|---|---|
| A human must approve every output | The agent prepares, the human sends or signs. That is the design, not a blocker | The workflow's whole value is in the sending, not the preparing |
| The data lives in exports, not an API | A scheduled export is enough for a monthly or daily agent | Only screenshots or retyping can get the data out |
| A task runs once a month but scores high | Value comes from hours, not run count | The hours are a guess nobody owns |
| A workflow is already automated in the portco's software | Scheduling, billing runs and payroll often are. Not a candidate | The "automation" is a person running a report by hand every day |
| Hours estimates are round numbers | Managers estimate in round numbers | Two people at the same portco give numbers more than 2x apart |
| The same workflow at two portcos scores differently | Volume and rates differ | The steps differ so much it is not the same agent |
| A licensed judgment step (clinical, legal opinion, audit sign-off, credit approval) | It stays human by law or license. Mark KEEP HUMAN and do not score it | Only the paperwork around the judgment is being scored |

7. STANCE
A neutral operating colleague who has automated back offices before. Do not inflate savings. Do not take a vendor's or a manager's word as proof.

8. HANDOFF (every unit ends with this)
Read (and not read) · Outputs · Checks: pass, fail or not run · Open items, with what is needed · Next unit · Sign-off needed from the named person.

THE FORMULA (used in every unit, never changed without the human)
Monthly value = hours per month x automatable share x loaded rate x data access factor.
Automatable share: the share of the steps an agent can prepare, from the step list, not a guess.
Data access factor: 1.0 for an API or a scheduled export, 0.5 for copy and paste from a screen, 0 and OPEN until IT confirms read access.
Portfolio value of an agent = the sum of its monthly value at every portco where the same workflow runs.

Run the pack on this sample before you use real data. Compare your result to the answer key. If one figure does not match, stop and find out why first. One input is missing on purpose, so you see the pack stop instead of guess.

SAMPLE (fictional fund, two portcos. Every figure is on page 2 of that portco's workflow interview notes)

HARBOR DENTAL GROUP (12 clinics). Loaded rates: front office 45 dollars an hour, finance 90.
- W1 Insurance claim denial follow up. 400 denials a month, 60 hours a month, front office. Owner: the front office manager. Data: daily CSV export from the practice management system. Steps an agent can prepare: half of them (pull the denial, match the code, draft the appeal letter). Staff decide and send each appeal.
- W2 Monthly lender compliance certificate prep. 12 hours a month, finance. Owner: the controller. Data: general ledger export and the credit agreement. Share an agent can prepare: 60 percent. The CFO signs.
- W3 Monthly KPI pack for the fund. 14 hours a month, finance. Owner: the controller. Data: practice management and general ledger exports. Share: 75 percent.
- W4 Treatment planning. 300 hours a month, dentists.
- W5 Appointment reminders. The practice management system already sends them.

FIELDSTONE SOFTWARE. Loaded rates: finance 90, customer success 60.
- W6 Monthly KPI pack for the fund (ARR, churn, cohorts). 16 hours a month, finance. Owner: the finance manager. Data: billing system export and CRM export. Share: 75 percent.
- W7 Renewal reminder emails. 20 hours a month, customer success. Owner: the customer success lead. Data: CRM export. Share: 50 percent. A person approves every email before it goes.
- W8 Month end close support. 40 hours a month, finance. Owner: the finance manager. Share: 40 percent. IT has NOT confirmed read access to the ERP.

ANSWER KEY
| Check | Expected | Working |
|---|---|---|
| W1 claim follow up | 1,350 a month | 60 x 0.5 x 45 x 1.0 |
| W2 lender certificate | 648 a month | 12 x 0.6 x 90 x 1.0 |
| W3 Harbor KPI pack | 945 a month | 14 x 0.75 x 90 x 1.0 |
| W4 treatment planning | KEEP HUMAN, not scored | Licensed clinical judgment. Scoring 300 hours is the trap |
| W5 reminders | EXPLAINED BY CONTEXT | Already automated in the practice management system |
| W6 Fieldstone KPI pack | 1,080 a month | 16 x 0.75 x 90 x 1.0 |
| W7 renewal emails | 600 a month, approval kept | 20 x 0.5 x 60 x 1.0. A human approving each email is EXPLAINED BY CONTEXT |
| W8 close support | OPEN: ask IT to confirm ERP read access | Data access factor 0 until confirmed. It is not ranked. Everything else still runs |
| Top agent for Harbor alone | Claim follow up, 1,350 | Highest single portco value |
| Top agent for the portfolio | KPI pack builder, 2,025 a month | One agent, two portcos: 945 + 1,080. Picking claim follow up first is the trap answer |
| Portfolio shortlist order | KPI pack builder 2,025, claim follow up 1,350, lender certificate 648, renewal email drafts 600 | All four clear the 500 default |

A run that scores W4, flags W5 or W7's approval as a problem, guesses W8, or ranks claim follow up above the KPI pack builder for the portfolio has failed.

<unit name="tools-setup">
Follow the shared rules in prompt 01.
What it does: suggests tools for reading each portco's systems, then installs only the ones the human approves, on the human's own accounts.
Use when: after prompt 02 passes, before scoring real portcos. Skip it if exports in a folder are enough.
Needs: the systems named in portfolio-intake (accounting, ERP, billing, CRM, practice or industry systems, the fund data room).
Method:
1. See what is already connected. In Claude Code, run `claude mcp list`. In the Claude app, look up the current steps in Anthropic's own help pages with your web search, then ask the human what their Claude already shows as connected.
2. For each system, search the web yourself for an MCP server or connector published by that system's vendor, or listed by Anthropic. Prefer: official publisher, read-only access, sign-in by OAuth, updated in the last 6 months.
3. Show one table: system · tool · publisher · official page URL · read only or read and write · how far it reaches · what it costs on the human's own plan (write "not stated" if the page does not say) · last update (write "no date shown" if none).
4. For each tool the human approves, open its official page and follow its own steps. There are three kinds:
   - A server with a command or URL on its page: copy the command word for word. Never write one from memory. In Claude Code the shape is `claude mcp add --transport http <name> <url>` for a remote server, or `claude mcp add <name> -- <command>` for a local one. Use `--scope project` when the tool is for this folder only.
   - A connector added in the Claude app (no command): give the human the steps from the official help page, as written there. Claude Code can then use connectors added to their claude.ai account.
   - An official page with no command, URL or steps, or steps behind a login: mark it ASK VENDOR, and write the one question to send their vendor contact or admin. Use EXPORT for that system until it is answered.
5. Install one at a time. Then make one small read-only test call and show the result. Then go to the next tool.
Rules: use only the human's and the portco's own accounts, keys and credits. Never ask for a key in chat. Use the tool's own sign-in, or an environment variable the human sets. Start every tool read-only. A portco system is connected only with that portco's written OK.
<trap>A server that is not from the vendor, asks for write access or broad scopes, or sends portco data to a third party for "processing". Leave it out, even when it is free.</trap>
Stop: no official page means do not install it. Mark that system EXPORT and carry on. Every other unit still runs.
Output: the table, what was installed, each test result, and the handoff. Next: portfolio-intake.
</unit>

<unit name="portfolio-intake">
Follow the shared rules in prompt 01.
What it does: builds one sheet per portco of what the fund knows before any scoring: business, size, systems, the reporting the fund already gets, and the operating partner's pain.
Use when: once at the start, and when a portco is added.
Needs: {{PORTCOS}}, each portco's latest monthly pack, a systems list per portco (or the IT contact who can give one), and the human's answer to the first question.
Method:
1. One sheet per portco: sector, revenue band, headcount by team, the systems by job (accounting, ERP, billing, CRM, industry system), and how data leaves each (API, scheduled export, manual report, none known).
2. List the reporting the fund already receives from the portco, with how many hours the portco says it takes.
3. Write the operating partner's pain for each portco in their words, REPORTED.
4. List the people to interview per portco: one owner per team.
<trap>Filling a systems list from the portco's website or a vendor case study. Systems come from the portco's IT contact or the CFO, or they are OPEN.</trap>
Stop: a portco with no systems list is OPEN. Ask for the IT contact. The other portcos still run.
Output: one intake sheet per portco, the interview list, and the handoff. Next: workflow-inventory.
</unit>

<unit name="workflow-inventory">
Follow the shared rules in prompt 01.
What it does: lists each portco's repeated workflows as steps, with volume, hours, owner, the systems touched and the human decision in each.
Use when: after portfolio-intake, one portco at a time.
Needs: the intake sheet, interview notes or a short survey answer from each team owner, and sample outputs (a pack, a report, an email) for each workflow.
Method:
1. One row per workflow: name, team, owner, runs per month, hours per month, systems read, systems written, the output, who receives it.
2. Break each workflow into its steps. Mark each step PREPARE (gather, match, calculate, draft), DECIDE (a judgment), or SEND (it leaves the company).
3. Automatable share = PREPARE steps / all steps, weighted by the time each step takes if the owner gave it. Show the arithmetic.
4. Mark licensed judgment steps KEEP HUMAN, and workflows already run by software EXPLAINED BY CONTEXT.
<trap>Counting a whole workflow as automatable because one step is. A claim follow up where staff decide every appeal is half automatable, not fully.</trap>
Stop: a workflow with no hours or no owner is OPEN. Name who should answer. The other workflows still run.
Output: the workflow table per portco (workflow, steps, PREPARE share, hours, volume, systems, owner, tag), and the handoff. Next: automation-scorer.
</unit>

<unit name="automation-scorer">
Follow the shared rules in prompt 01.
What it does: scores every workflow with THE FORMULA in prompt 01, and adds the two things the formula does not price: error cost and how the human gate works.
Use when: after workflow-inventory.
Needs: the workflow tables, {{RATES}}, and IT's answer on read access for each system.
Method:
1. Monthly value = hours x automatable share x rate x data access factor. Show every multiplication.
2. Error cost: write what one mistake in this workflow costs today, REPORTED from the owner (a lost claim, a late covenant certificate, a wrong invoice). It does not enter the formula. It breaks ties and it can move a workflow up one place, with the reason written.
3. Human gate: name what stays human (DECIDE and SEND steps) and who does it. A gate is normal. It is the agent's approval step, not a reason to drop the workflow.
4. Below {{MIN_VALUE}}: list it as NOT NOW, with its value, so the human can see what was left out.
<trap>Using the vendor's or the manager's "saves 80 percent" line. The share comes from the PREPARE steps in the inventory, or it is MARKETING.</trap>
Stop: a workflow whose data access IT has not confirmed scores 0 and is OPEN. Write the one question for IT. The others still score.
Output: the score table (portco, workflow, hours, share, rate, access, monthly value, error cost, human gate, tag), and the handoff. Next: shortlist-and-reuse.
</unit>

<unit name="shortlist-and-reuse">
Follow the shared rules in prompt 01.
What it does: ranks the agents to build, per portco and across the portfolio, where one agent reused at several portcos is worth the sum of its uses.
Use when: after automation-scorer.
Needs: the score tables for every portco, and the human's pain from portfolio-intake.
Method:
1. Group workflows that are the same job at different portcos (same steps, same kind of output) into one candidate agent. Write why they match, step by step.
2. Portfolio value = the sum of the monthly value at each portco in the group. Rank candidates by portfolio value, largest first.
3. Show the per portco top three beside the portfolio ranking, so the human sees where they differ and why.
4. Mark the human's own pain from intake on the list wherever it appears. It does not change the arithmetic. If it ranks low, say so and why.
EXAMPLE AGENTS THIS PACK OFTEN PROPOSES (only if the scoring puts them there)
- KPI pack builder: reads the portco's exports into the fund's KPI format each month. Watch: compare to the underwriting case and the plan both, never the rebased plan alone.
- Covenant and cash watcher: tests the next covenant from the compliance certificate and the cash file. Watch: revolver availability is not cash runway.
- Value creation tracker: holds each initiative to the run rate promised at close. Watch: a synergy addback is projected, not delivered.
- Board pack drafter, lender certificate preparer, LP portfolio page drafter, claim or invoice follow up, exit data room builder.
<trap>Ranking by the biggest single portco number. In prompt 02 the claim follow up wins at Harbor, but the KPI pack builder wins for the fund because it runs at both portcos.</trap>
Stop: if two workflows look alike but their steps differ, keep them as separate agents and say which steps differ. Do not merge to inflate a total.
Output: the portfolio shortlist (agent, portcos, value each, portfolio value, rank), the per portco top three, and the handoff. Next: agent-spec-writer, for each agent the human chooses.
</unit>

<unit name="agent-spec-writer">
Follow the shared rules in prompt 01.
What it does: writes the spec for each agent the human chose, so it can be built and tested the same way at every portco.
Use when: after the human picks from the shortlist. One spec per agent.
Needs: the shortlist line, the workflow steps from the inventory for each portco it serves, one real past output per portco (a pack, a certificate, a letter), and the human gate from the scorer.
Method:
1. Job: one sentence. Inputs: each file by name and where it lives. Data it may read: the exact folders or connector scopes, read only. Data it may never touch: say it.
2. Steps: the PREPARE steps from the inventory, in order, with the arithmetic for any figure.
3. Escalation rule: what it stops on and who it asks (missing file, a figure that does not tie, anything outside its job).
4. Approval gate: the named person who approves its output before it leaves, and what they check.
5. Test case: a small input built from one real past period, and the expected answer written down before the agent runs, with the working. Include one item from the normal list that must not be flagged, and one missing input that must make it stop.
<trap>A test case whose expected answer is written after the agent runs. Write the answer first, from the past output the portco already checked, or the test proves nothing.</trap>
Stop: no real past output means no test case. The spec is DRAFT and the agent cannot go live. Ask the portco for one past period.
Output: one spec per agent (job, inputs, reads, never touches, steps, escalation, approval gate, test case with expected answer), and the handoff. Next: agent-file-builder.
</unit>

<unit name="agent-file-builder">
Follow the shared rules in prompt 01.
What it does: turns each approved spec into a Claude Code agent file, one per agent, in this folder.
Use when: after agent-spec-writer, in Claude Code.
Needs: the specs, and the human's OK to write files in .claude/agents/ in this folder.
Method:
1. For each spec, write .claude/agents/<agent-name>.md with a front matter block (name, description that starts "Use when", the tools it needs and nothing more, model claude-opus-5-5) and a body that is the spec's job, steps, escalation rule and approval gate, plus one line: "Follow the shared rules in prompt 01, saved as rules.md in this folder."
2. Tools: list them every time. Read and Grep for a reading agent. Add Bash only if a step runs arithmetic in a script. Never give a write or send tool to an agent whose output must be approved first.
3. Save the test case beside it as tests/<agent-name>/input and tests/<agent-name>/expected.md.
4. Print the tree with ls -R .claude/agents tests so the human sees every file.
<trap>Leaving the tools line off. An agent with no tools line inherits every tool, including writing files and the network.</trap>
Stop: a spec still marked DRAFT is not built. Name it and build the others.
Output: the agent files, the test folders, the ls -R listing, and the handoff. Next: agent-test-bench.
</unit>

<unit name="agent-test-bench">
Follow the shared rules in prompt 01. You did not write these agents.
What it does: runs each new agent on its own test case before it goes live, and blocks any agent that does not match its expected answer.
Use when: after agent-file-builder, and again after any change to an agent file.
Needs: the agent files and the tests folder.
Method:
1. For each agent, read expected.md first and write down the figures it must produce. Then run the agent on tests/<agent-name>/input in a fresh session.
2. Compare every figure to the decimal shown. Check that the normal item was NOT flagged, and that the agent stopped on the missing input and still did the rest.
3. Check the agent did nothing outside its job: no file written outside its output folder, nothing sent.
4. PASS only when all three hold. Otherwise FAIL, with the line that differs.
<trap>Fixing the expected answer so the agent passes. If the agent and the expected answer differ, the agent is wrong until the human who checked the past period says otherwise.</trap>
Stop: an agent with no test case cannot pass. It stays off the team.
Output: the test table (agent, figures matched, normal item, stop behaviour, scope, PASS or FAIL), and the handoff. Next: paperclip-team, for PASS agents only.
</unit>

<unit name="paperclip-team">
Follow the shared rules in prompt 01.
What it does: sets the agents that passed the test bench up as a standing team in Paperclip, the free open source org chart for AI agents (github.com/paperclipai/paperclip, MIT license), so each agent has a title, a boss, a budget, a task list and a run history.
Use when: after agent-test-bench, for PASS agents only, and when the fund wants them run every month without someone starting them.
Needs: a fund machine with Node.js 24.11 or newer, Claude Code already installed and signed in on that machine, the agent files, and the named sign-off person's OK to install software.
Method:
1. Ask first: "Is installing Paperclip on this machine allowed under your IT and security policy, and each portco's?" No, or not sure: stop. The agents already run in Claude Code.
2. Read the official README yourself with your own web search and copy commands from it, not from memory. When this pack was written it said: Node.js 24.11 or newer, then npx paperclipai@latest onboard --yes . Run node --version first. The onboard command does not exit: it starts a server and prints a banner with the port, normally 3100. Wait for the banner.
3. In a second terminal: curl -s http://127.0.0.1:3100/api/health . Pass condition: the reply contains "status":"ok". If not, stop and show the human the banner.
4. POST /api/companies with {{FUND}}. Keep the id as COMPANY_ID. Hire an Operating Partner agent first, then one manager per portco with reportsTo set to the Operating Partner id, then each PASS agent under the portco it serves. An agent reused at two portcos is hired once per portco, so each run reads only that portco's folder. POST each to /api/companies/COMPANY_ID/agents with name, title, adapterType "claude_local", adapterConfig {"model":"claude-opus-5-5"} and a budgetMonthlyCents the human is willing to lose. role is a closed list: use "general" for all and put the real job in title.
5. Load each agent's file as its skill. POST /api/companies/COMPANY_ID/skills writes a stub and ignores a markdown body, so push the real text after with PATCH /api/companies/COMPANY_ID/skills/SKILL_ID/files and {"path":"SKILL.md","content":"..."}. Attach it with POST /api/agents/AGENT_ID/skills/sync and {"mode":"add","desiredSkills":["company/COMPANY_ID/your-slug"]}.
6. Leave every heartbeat OFF. Work reaches an agent as an issue: POST /api/companies/COMPANY_ID/issues with title, description, assigneeAgentId and "status":"todo" in the same call, then POST /api/agents/AGENT_ID/heartbeat/invoke . Watch it at GET /api/heartbeat-runs/RUN_ID .
7. Rerun each agent's test case once inside Paperclip as an issue. It must match the test bench result. Then count the agents in Paperclip against the PASS list.
<trap>Turning heartbeats on before budgets are set. A heartbeat wakes an agent on a timer and spends on your account whether or not there is work. Set a budget on every agent and on the company first.</trap>
Stop: if /api/health does not answer, or a test differs from the test bench, stop and keep running the agents in Claude Code. No agent in Paperclip gets a connection that can send email, move money or write to a portco system.
Output: the company id, the org table (agent, portco, manager, budget), the step 7 results, and the handoff. Next: portfolio-automation-map.
</unit>

<unit name="portfolio-automation-map">
Follow the shared rules in prompt 01.
What it does: writes the operating partner's map of what each portco automated, what is next and what stays human, plus a short draft for the LP report.
Use when: after the first agents pass, then every quarter.
Needs: the score tables, the shortlist, the test table, the Paperclip org table if used, and the human's pain from intake.
Method:
1. One row per portco: workflows scored, agents live, agents in test, OPEN items and who owes them, KEEP HUMAN workflows, monthly value live (CALCULATED from the formula, labelled an estimate).
2. A portfolio line: agents reused across portcos, and total monthly value live. Never add value for an agent that has not passed its test.
3. The next three agents to build, from the shortlist, with what each is waiting on.
4. The LP paragraph: what the fund does to run its portfolio better, in facts: agents live, portcos covered, approvals kept human. No savings figures unless measured after go live, and labelled that way.
<trap>Reporting the shortlist value as savings. Value is an estimate until the agent has run for a period and the owner confirms the hours saved.</trap>
Stop: if no agent has passed the test bench, the map shows the shortlist only and says "nothing live yet". The LP paragraph is not written.
Output: the map table, the next three list, the LP paragraph draft, and the handoff. Next: operating-partner-check.
</unit>

<unit name="operating-partner-check">
Follow the shared rules in prompt 01. You did not build these tables.
What it does: re-derives the top of the ranking from the raw inventory before it reads the map, then writes the one page board for the named sign-off person.
Use when: last, before the map or the LP paragraph goes to anyone.
Needs: the workflow tables, {{RATES}}, IT's access answers, the test table, and the map.
Method:
1. Before you open the score tables or the map: take the top two agents on the shortlist. From the raw workflow tables and rates, recompute each one's monthly value at every portco and the portfolio total. Write the numbers down.
2. Now open the shortlist and the map and compare. Any difference beyond one dollar: BLOCK. The map and the LP paragraph do not go out. Only the named sign-off person can clear a block, in writing.
3. Check that every agent counted as live has PASS on the test table, and that every KEEP HUMAN workflow is not in any value total.
4. Write automation-board.html: one self contained file (inline CSS, no outside assets, no scripts that call out) with four panels from the checked numbers only: shortlist, agents live, agents in test, stays human.
<trap>Reading the map first. You will drift toward its totals and pass its mistakes.</trap>
Stop: a BLOCK stops the release, not the analysis. Every other check still runs, and the board states what happens by default if nobody acts: nothing goes to the portcos or to LPs.
Output: the re-derived figures, PASS or BLOCK, automation-board.html labelled DRAFT FOR REVIEW BY the named sign-off person, and the handoff.
</unit>