FPF Reference

Automation Playbook

Use this page when you want agentic help around fpf-memory without collapsing every job into one agent.

What this page is

This is the public operating model for fpf-memory automation. It explains the roles, what each role may do, what evidence it should produce, and where user approval is required.

It is not a list of private automation records, thread IDs, local paths, account credentials, or personal scheduling details.

Methodology

Keep role, capability, promise, work, and evidence separate.

  • Role: what stance the automation takes.
  • Capability: what the automation can technically inspect or change.
  • Promise: what the automation is expected to provide.
  • Work: what an actual run did.
  • Evidence: URLs, commands, PRs, discussions, checks, screenshots, or logs that prove the work.

The main safety rule is simple: discovery roles stay read-only, implementation roles make PRs, and merge or publishing authority stays explicit.

Role map

RolePromiseMay doMust not do by defaultOutput artifact
Dogfood/product scoutAct as one product user role and report friction.Try docs, MCP, CLI, evaluator, deploy evidence, and onboarding flows.Edit repo files, create PRs, open issues, comment, merge, or post externally.Role/job report with evidence, friction, severity, and handoffs.
Discussion stewardKeep GitHub Discussions actionable.Inspect discussions, issues, and PRs; dedupe signals; maintain a Top 3 work list.Implement fixes or create noisy new threads by default.Discussion change report and issue-conversion recommendation.
Implementation PR agentTurn one ready item into a bounded PR.Edit code/docs, validate, open or update one PR.Self-merge or perform broad product scouting.PR with source links, validation output, and residual risk.
PR review and merge captainKeep PRs moving with independent judgment.Review PRs, check CI/reviews/mergeability, comment on blockers, merge when policy is met.Implement fixes or silently wait on blocked PRs.Merge/no-merge decision with evidence.
Manager briefCompress automation state for the user.Read automation memory, repo state, PRs, discussions, docs, and hosted MCP health.Replace the specialist roles or make external commitments.Product readiness, changed, validated, Top 3 next actions, decisions needed.
Technical architectMake periodic system-level judgment.Review MCP server, index/runtime, docs/adoption UX, CLI, evaluator, packaging/deploy, CI, and automation health.Create implementation work unless explicitly asked.Architecture state, risks, recommendations, handoffs, and stop/replan triggers.
Growth and publishing scoutTurn validated evidence into draft public material.Draft Medium/Substack posts, short social posts, README/forum blurbs, and outreach notes.Publish, email, DM, post, or log into external accounts without explicit approval.Share packet with audience, proof points, caveats, links, and call to action.

Workflow

Dogfood/product scout
  -> friction evidence
Discussion steward
  -> ready work item
Implementation PR agent
  -> validated PR
PR review and merge captain
  -> merge or blocker
Manager brief

Technical architect
  -> system risks and decisions
Manager brief

Dogfood/product scout
  -> validated proof points
Growth and publishing scout
  -> draft share packet
Manager brief

Access and authority

CapabilityNeeded byDefault
Local repo and public product read accessAll rolesAllowed for evidence gathering.
GitHub read accessAll roles that inspect discussions, issues, PRs, and CIAllowed for evidence gathering.
GitHub write accessImplementation PR agent and PR review/merge captainAllowed only within their role boundaries.
External publishing accountsGrowth and publishing scoutDraft-only unless the user explicitly approves a specific publish/send action.
Secrets, billing, deploy settings, destructive actionsUser or explicitly delegated operatorPrepare instructions; do not perform final actions by default.

For purchases, subscriptions, billing changes, account changes, or external publishing, the automation may prepare the flow and draft the copy. The user performs or explicitly approves the final action.

Merge policy

Implementation and merge authority are separate.

A PR may be merged by the review/merge role only when:

  • required CI and branch-protection checks are green;
  • the PR is not draft and is mergeable;
  • there is no unresolved blocking review or requested change on the current head;
  • validation evidence is sufficient for the changed surface;
  • the PR has independent approval or an approved fast-track condition for the current head.

If any condition is missing, the role should report the exact blocker rather than waiting silently.

Publishing and outreach packets

Off-GitHub publishing is prepared as a draft packet. The packet should include:

  • channel and audience;
  • promise being made;
  • product ability that supports the promise;
  • observed performance or evidence;
  • caveat that should stay visible;
  • canonical links;
  • suggested call to action;
  • approval needed before sending or publishing.

Medium or Substack draft packet

Channel: Medium or Substack
Audience: agent-tool builders and technical leads who keep pasting large framework specs into coding chats

Working title:
Stop pasting the whole spec: using fpf-memory as bounded FPF context for agents

Hook:
FPF work needs exact IDs, routes, and evidence, but a whole-spec dump is the wrong interface for daily agent work.

Claim:
fpf-memory turns the published FPF spec into deterministic lookup surfaces: MCP tools, CLI queries, and generated docs.

Proof points:
- compiler-backed vectorless index;
- hosted MCP endpoint;
- generated docs and work packets;
- deterministic retrieval first, optional synthesis second.

Caveat:
Do not claim broad adoption or benchmark superiority unless current evidence supports it.

Call to action:
Try one bounded FPF query through MCP before putting the whole specification into a prompt.

Short social post packet

Channel: LinkedIn, X, Mastodon, or another short-form surface

Draft:
Built a small MCP-oriented runtime for FPF.

fpf-memory compiles the published FPF spec into deterministic lookup surfaces so agents can ask for exact routes, IDs, docs, and bounded context instead of loading the whole spec.

Useful for PR review, project alignment, spec writing, and adoption UX checks.

Docs: https://fpf.sh/
Connect MCP: https://fpf.sh/connect-mcp

Caveat: deterministic retrieval first; synthesis is optional.

One-to-one outreach packet

Recipient type:
Someone building MCP tools, coding agents, or structured reasoning workflows.

Subject:
Short FPF/MCP artifact I wanted to share

Draft:
Hi <name>,

I have a compact artifact that may be relevant to your agent/MCP work.

fpf-memory is a compiler-backed runtime for the published First Principles Framework spec. The basic idea is to avoid pasting the whole framework into agents. Instead, the agent can retrieve exact FPF routes, IDs, generated docs, and bounded context through MCP or CLI.

The current material:
- Website: https://fpf.sh/
- Connect MCP: https://fpf.sh/connect-mcp
- Hosted endpoint: https://mcp.fpf.sh/api/mcp/fpf_memory/mcp

The claim I am comfortable making right now is narrow: it is useful for bounded FPF lookup and agent workflows that need evidence-backed framework context. I am not claiming broad adoption or benchmark superiority yet.

If you are open to it, I would value a quick critique of the MCP onboarding path.

Approval checklist

Before anything leaves GitHub or a local draft:

  • The channel is named.
  • The audience is named.
  • The claim is backed by current evidence.
  • The caveat is visible.
  • The user has approved the exact copy or the exact destination.
  • No private repo, account, credential, thread, or local-machine detail is included.

Done condition

The automation system is healthy when each role can answer:

  • what it inspected;
  • what it changed, if anything;
  • what evidence supports the result;
  • what it cannot do without approval;
  • who owns the next action.

Last Updated: 5/9/2026, 11:05:33 PM