Peach Pilot
PeachOS architecture

PeachOS architecture.

One canonical repo as the company brain, human working directories that clone it, external systems wired in, and the agent fleet kept isolated. Grounded in the Hannah / Carl synthesis + the audience-split and AGENTS.md daisy-chain decisions.

Governing rule - one home per artifact

Every artifact has one canonical home. The other surface references or embeds it, never co-owns it. That is what kills dual-source drift.

GitHub is the brain, Notion is how humans read and comment on it, Drive is how finished things leave the building.

The flow is repo → distilled into Notion, never the reverse for product-dev artifacts.

Canonical source Human working dirs External systems Agent fleet (isolated) Boundary / no-fly zone
Layer 1 - Canonical source

github.com/peachpilot-ai/peachos (single repo)

.claude/ + .cursor/

  • skills/ (team-shared)
  • agents/ (e.g. onboarding)
  • commands/ (slash commands)
  • hooks/ (session-start, etc.)
  • team-learnings.md

product/ (products only)

  • right-quote/ (app spec, specs, marketecture; admin tabs A1-A4 live here, not a separate product)
  • peach-live/ (live-call coaching, bolts onto Right Quote)
  • chargebacks/ (win-back)

cross-product (top-level siblings)

  • knowledge/ (personas, industry-knowledge, competitive-and-vendor-research)
  • strategy/, principles/, processes/
  • customers/safe-life/ (calls + context); meetings/ (standup / internal / vendor-discovery)
  • brand/ (visual assets + positioning / messaging / voice)

team/ + root files

  • adoption-playbook.md
  • onboarding-guides/ (general + role-specific)
  • retros/
  • AGENTS.md (canonical content)
  • CLAUDE.md (1-line pointer to AGENTS.md)
  • README.md, MINIMAL-SETUP.md
AGENTS.md is canonical; CLAUDE.md is a one-line daisy-chain pointer (Avi pattern). Every folder gets its own AGENTS.md routing table.
Layer 2 - Human working directories

Each person's working dir is a git clone of the repo

Mario
CEO
Strategy + business review
Adds meeting transcripts + content; reviews strategy. Works via GitHub UI / Notion (or Claude Code)
Chris
Head of Engineering
Engineering leadership, partner to Ben
Reads repo for product + principles context; reviews PRs
Aaron
Head of Product
Product Leadership
Claude Code + Cursor; runs ticket-spec, linear-sync, agent-fleet-catalog skills
Joseph
Assistant to Mario
Coordination + ops; built much of Notion
Adds transcripts, action items, decisions; works in Notion + repo (GitHub UI or Claude Code)
Avi
Eng
SLP-MVP / reference work
Claude Code + Codex (daisy chain works for both)
Soham
Eng
Peach Live voice stack
Cursor (reads AGENTS.md natively)
Ben
Head of Architecture
Constitution + Hermes fleet
Owns Constitution L1; reads repo for L2+ context
Chadani
QA
Manual QA lead
Claude Code: runs pp-qa-runner skill on Linear tickets
Natalie + Jim
QA
Hive QA collaborators
Same as Chadani: pp-qa-runner skill
Grayson
Intern, started 6/3
Chargebacks scope
Onboarding via /onboarding agent
Each clone is the team member's working directory for team work. Claude Code / Cursor read .claude/ and .cursor/ in-place. No bootstrap copy step. git pull updates skills + content atomically. Personal tooling (private notes, time-tracking, personal scripts) stays outside the clone or gitignored.
Layer 3 - External systems

Integration via MCPs and skills

Linear
Product work tickets, ACs, QA comments. Source of truth for in-flight work.
Notion
Coordination layer: action items DB, decisions log, playbook docs, team review of strategy
Slack
Comms; standup notifications; threading per the team norm. Slack MCP for read/write where wired
Google Drive
Time-tracking sheet, brand assets, large attachments. Drive MCP wired
Gmail
Vendor outreach, external comms. Gmail MCP wired
GitHub
Hosts the canonical repo. PRs are the contribution mechanism per Hannah's pattern
Granola
Product-call recorder. A shared skill ingests transcripts into customers/{name}/calls - redacts sensitive content (salaries, PII, disparaging remarks) on ingest, stores a summary by default with the full transcript as drill-down.
Layer 4 - Agent fleet (isolated)

Hermes agent fleet - isolated from the repo (paused during the MVP push)

Reads from

  • Linear ticket descriptions
  • Linear-attached ticket-spec documents
  • Ben's Constitution overlay (L1 stack rules)
No-fly zone: Hermes does NOT read the PeachOS repo. Strategic context, principles, decisions, and customer accounts live in the repo for human teammates and their AI editor sessions only. Any context the fleet needs gets embedded in the Linear ticket spec by the spec author. This avoids dual source-of-truth drift between the repo and Linear. The agent fleet also cannot move tickets past Ready for QA; humans own Awaiting Release and Done.

Sync flow: how a teammate gets and updates PeachOS

Onboarding (once): git clone peachpilot-ai/peachos → cd peachos → open Claude Code / Cursor here → /onboarding agent walks them through their role
Daily: git pull → skills + principles + decisions update in place → no copy / no bootstrap script needed
Contributing: edit files locally → git commit + push → PR with tagged reviewer → merge → next teammate's git pull picks it up
No special "sync from GitHub to user's machine" step. The working directory IS the clone. Claude Code reads .claude/skills/ in-place. This is Hannah's pattern. Aaron's personal files (LOG.md, NEXT.md, time-tracking/) stay gitignored or move to a personal/ subfolder.

Skill categorization

CategorySkill / ScriptWho runs itPriorityNotes
Product Development Cycle pp-bug-ticketAnyone filing a bugTier 1Promoted per Aaron. Scaffolds Linear bug ticket: bug label, severity, regression_<name> test scaffold, prior-bug registry update, repro steps
pp-qa-runnerChadani / Natalie / Jim (self-serve)Tier 1PASS/FAIL comment generator following QA Process Guide §7/§8; pulls ACs from live Linear ticket; severity-tagged; posts via Linear MCP
pp-ticket-specAaronTier 2Enforces artifact-writing-principles.md: concrete-values rule, Gherkin multi-line, 8-section structure, prior-fixes-preserve check
pp-linear-syncAaronTier 2Keeps GitHub repo and Linear in sync bidirectionally: push local spec changes to Linear ticket description; pull Linear edits back to repo. Diff-and-confirm before write
pp-agent-fleet-catalogAaronTier 2Inventory tickets created by Hermes fleet in a window. Surfaces review-worthy items (sub-issues, new bugs filed by agents). Visibility into autonomous fleet activity
pp-feature-launch-gateAaronTier 3Pre-launch repo completeness check (Hannah pattern adapted): app spec, ticket specs, QA pass comments, principles compliance. v1 ship-gate
Team Coordination pp-standupWhole team (anyone running daily standup)Tier 1Transcript paste → meeting note + action item extraction + memory updates + Notion action-item DB write. Used by whoever facilitates
pp-decision-log-entryWhole teamTier 2Decision record with reasoning. Full + quick variants per Hannah. Writes to the Notion decisions log (Notion is the decisions home, not the repo).
pp-call-ingestWhoever takes the call / AaronTier 3Proactively redacts sensitive / PII / salary and disparaging content from product + customer call transcripts before they enter PeachOS; summary-default with drill-down to the full transcript. One common ingestion skill across customers (Granola source).
pp-customer-call-summaryWhoever takes the callTier 3Structured call summary + insight table + feature-request table + follow-up email + Slack draft. Per Aakash's reference skill. Mostly for Safe Life calls
Personal tooling (not team-shared) e.g. time-track, daily-logIndividualOut of scopePersonal scripts and notes live outside the shared .claude/skills/ tree. Anyone can keep their own tooling; not maintained or reviewed by the team
Bootstrap / Onboarding /onboarding agentNew hires (Grayson 6/3, future)Tier 2Hannah pattern: interactive walk-through. New hire clones repo, opens CC, asks the agent what to read first. Routes by role (PM / Eng / QA / Intern)
peachos / architecture.mockup.html Structure: peachos / file-structure-proposal.mockup.html