Persimmon

Persimmon — Master Skill

The single entry point for any work in a Persimmon project. Read this first; it enforces the workflow gate, then points you at the right domain mother for the task at hand.

Trigger

• Any Persimmon client work
• "Where do I start?" / "Which skill should I use?"
• "Persimmon defaults"
• "I just opened this project — orient me"

Workflow gate (HARD RULE — read before anything else)

Before invoking ANY domain mother on non-trivial work, you MUST first invoke the workflow mother. The workflow layer forces brainstorm-before-code discipline so changes ship with an approved spec, a plan, and a business-meaning translation for the client's operators.

On internal-tool projects (see .claude/project-type), refuse to write code without:

1. An approved spec in docs/specs/, AND
2. A plan in docs/plans/ for the current task.

If both are missing, respond: "No approved spec/plan for this work. Invoke workflow to brainstorm and plan first."

On marketing-site projects, a spec is required only for new pages/sections; minor edits bypass.

Trivial bypass examples (no workflow needed): copy/text changes, one-line Tailwind/CSS, README/CLAUDE.md edits, dependency version bumps, typos, reverting a recent commit. Rule of thumb: if the commit would mention a new file, schema/migration, route, Server Action, dependency, or use "feature/refactor" verbs — workflow is required.

Override: the user can type skip workflow: to proceed without the gate. The commit message footer gets Workflow: skipped by user for audit. If override fires on >20% of tasks, the bypass list is too tight.

If .claude/project-type is missing, ask once and offer to write it (internal-tool or marketing-site).

Session orientation — stage + project memory (read these first)

At the start of every session in a client project — before the workflow gate takes its first task — read two one-line markers and announce what they mean:

1. .claude/project-stage (prototype | mvp | demo | production | maintenance) — invoke meta-lifecycle-stage for the rules: prototype/mvp = push to main freely + Railway auto-deploy staging; demo = client review on staging; production = backup-gated + the quality-production-readiness gate; maintenance = most cautious (live data). If it's missing, infer + write it per meta-lifecycle-stage.
2. .claude/project-rules.md — the project's source-of-truth for deploy path, credential locations (never values), DB names, and where specs/mockups live — so you don't re-derive facts the project already recorded.

Both are auto-loaded by the SessionStart hook; confirm they exist and are current.

Apply skills, don't improvise — and recognize a stale install

Two failure modes corrupt the work even when the right skill exists:

1. Installed ≠ applied. Before any design/IA/schema/architecture decision, invoke and actually read the relevant skill — don't work from memory of what it "probably says." If a skill has a checklist, make a TodoWrite item per item. A decision you can't trace to a skill you read (or research you ran) is improvisation; stop and do one of them.
2. A referenced skill that isn't available means a stale/disabled plugin — not a skill that doesn't exist. Persimmon skills ship as a versioned plugin (persimmon@persimmon-labs); a project pinned to an older version, or with the plugin disabled at this scope, won't see skills added since. If you cite a skill (in a spec, plan, or review) and it's not in your available-skills list, do NOT do what a past session did — relabel real skills as "inline methodology" and write that fiction into the spec. Instead: flag it, re-sync via meta-skill-sync (claude plugin marketplace update persimmon-labs / enable at project scope), then invoke the now-available skill. Never silently downgrade a named skill to route around its absence.

The domain mothers

Lifecycle decision tree — when to invoke what

"I'm starting a new client project"

1. project-meta → meta-new-client-project — GitHub repo in the org, clone, scaffold docs, register
2. client-lifecycle → client-onboarding — site audit, brand extraction → PROJECT-BRIEF + BRAND-GUIDE
3. Scoping conversation — narrow SOW to MVP, agree on stack deltas
4. stack + frontend — Next.js 16 + TS skeleton, frontend-css-architecture + the right conventions child by project type
5. data → data-schema-design → data-prisma-pgvector — model rigor, schema, pgvector, HNSW
6. security → security-nextauth (+ security-hardening for runtime protections) — auth, trustHost, middleware
7. ai → ai-sdk-wrapper + ai-prompt-library — src/lib/ai/ baseline
8. infra → infra-s3-uploads → infra-railway-deploy → infra-github-ci
9. quality → quality-final-review + quality-production-readiness before client delivery
10. client-lifecycle → client-handoff — manual + training; client keeps code and keys

"I inherited / am extending an existing project"

1. Read the project's README.md and CLAUDE.md
2. project-meta → meta-project-xray to map pages, data flows, integrations
3. Match the change to a domain mother; go through workflow first if non-trivial

"I'm doing pre-delivery QA"

1. quality → quality-final-review orchestrates the review-* children
2. Address security-review, quality-review-* findings before sign-off

Persimmon defaults — one-screen summary

• Stack: Next.js 16 (App Router, RSC, Server Actions), TypeScript strict, Prisma + pgvector, Anthropic Claude SDK, NextAuth v5, Tailwind v4, Zod, Railway, GitHub Actions CI.
• Server Components by default; "use client" only for state/effects/browser APIs.
• Any page reading DB or auth() at request time exports const dynamic = "force-dynamic" (or the Railway build prerender crashes).
• All Claude traffic through src/lib/ai/claude.ts; all prompts in src/lib/ai/prompts.ts. Persist every AI output; never regenerate.
• Zod at every trust boundary (Server Actions, API routes, webhooks). unknown over any.
• Uploads: presigned URL → client PUTs directly to the bucket. Never proxy bytes through Next.
• NextAuth v5 behind Railway: trustHost: true; middleware reads x-forwarded-host.
• Prompt caching on stable system prompts that meet the per-model token minimum (Sonnet 4.6 = 2,048; Opus 4.6 / Haiku 4.5 = 4,096).
• Secrets server-side only — never NEXT_PUBLIC_*.

Cross-cutting anti-patterns banned

• Importing @anthropic-ai/sdk outside src/lib/ai/claude.ts
• Inline prompt strings in business logic (use ai-prompt-library)
• Reading DB/auth() in a page without force-dynamic
• any without a justified // eslint-disable + reason
• Unvalidated boundary input (missing Zod)
• Proxying upload bytes through Next instead of presigned PUT
• Regenerating an AI output that already exists
• Secrets in NEXT_PUBLIC_* or client bundles
• Querying a filtered-subset HNSW index without the filter

See also

• USER-GUIDE.md (repo root) — scenario-based usage with concrete commands
• docs/decisions/ — ADRs documenting why the repo is structured this way
• CLAUDE.md — base stack conventions every client project inherits