port-daddy-internal-dev

name	port-daddy-internal-dev
description	Contributor manual for agents working ON the Port Daddy codebase itself — the daemon, MCP server, FleetBar / Fleet Control Center, website, CLI surface, distribution mirrors, internal recovery ledger, and the named internal actors (Coxswain / Navigator / Cartographer / Lookout / Quartermaster + Shipwright). Use when editing the port-daddy repo. NOT for agents using Port Daddy on other projects (use port-daddy-agent-skill for that), and NOT distributed to public skill catalogs — this skill is private to the port-daddy repo.
license	FSL-1.1-MIT
allowed-tools	Read,Bash,Grep,Glob,Edit,Write
metadata	{"category":"Coordination","tags":["port-daddy","internal","contributor","daemon","fleetbar","mcp","distribution","release-surface","shipwright"],"pairs-with":["port-daddy-agent-skill","skill-architect"],"provenance":{"kind":"first-party","owners":["port-daddy"],"scope":"internal"},"authorship":{"maintainers":["port-daddy"]},"distribution":{"public":false,"note":"Sync to internal coordination paths inside the port-daddy repo only. Do not publish to windags-skills, .claude marketplaces, or other public catalogs. The port-daddy-agent-skill is the public-facing companion."},"mirrors":{"repo":"skills/port-daddy-internal-dev","codex":".codex/skills/port-daddy-internal-dev","claude":".claude/skills/port-daddy-internal-dev","agents":".agents/skills/port-daddy-internal-dev"}}

Port Daddy — Internal Contributor Manual

You are editing the Port Daddy codebase itself: the daemon, MCP server, FleetBar, Fleet Control Center, website, CLI, SDKs, distribution surfaces, the recovery ledger, and the internal actor inboxes. This skill is private to the port-daddy repo because most of what's here would be noise on a project that just uses Port Daddy.

For the public skill — how any agent on any project should drive Port Daddy — see the sibling port-daddy-agent-skill.

NOT For

• Agents on other projects driving Port Daddy as a coordination tool — that's port-daddy-agent-skill.
• General coding without a Port Daddy surface change.
• Distribution to public skill catalogs.
• Replacing the live daemon, recovery ledger, or actor inboxes as sources of truth — those still come first.

Operator vs Agent — the product rule

When designing or changing a Port Daddy surface, the test is "would the operator have to drop to a terminal to do this routinely?" If yes, the design is wrong. The operator's surface is FleetBar + the dashboard. pd CLI exists for agents and emergencies. Every routine operator action (configure credentials, restart daemon, see open feedback, harvest a roadmap entry, ack a salvage item) must have a FleetBar button or dashboard panel as its primary surface — CLI is the secondary path for agents and scripts.

Contributor implication: when you add a new actuator or data source, ship the FleetBar/dashboard affordance in the same slice when reasonable, or file a high-severity FleetBar feedback entry so cartographer promotes it to the roadmap before the CLI-only path ships to operators. Examples in flight: fleetbar-secret-management-with-provider-deeplinks, fleetbar-console-must-support-zoom-and-text-scaling.

Core Decision Tree

flowchart TD
    start[Edit lands on port-daddy] --> what{What changed?}
    what -->|CLI surface| cli[Update CLI help → references → website /docs/cli → MCP tools → skill bundle. Send Lookout drift report when scope > 2 surfaces.]
    what -->|Daemon API| api[Update lib + routes + OpenAPI + SDK ref. Run pd integration ready signals. Audit pd guard for new contracts.]
    what -->|MCP tool| mcp[Update mcp/server.ts + handshake test + skill catalog. Re-validate all 10 tool schemas.]
    what -->|FleetBar / Console| ui[Update Mac app + screenshots in references/fleetbar-and-console.md. Test from a clean install root.]
    what -->|Distribution mirrors| dist[Update brew formula sha256. Bump version in 4 places. Rerun install.sh end-to-end. Lookout review.]
    what -->|Internal actor| actor[Update routes/+ lib/ owning module + actor-roster.md + decisions/who-do-i-message.md. Backfill inbox tests.]
    what -->|Recovery ledger| ledger[Edit docs/recovery/CURRENT-WORK.md only via Cartographer/Navigator. Don't bypass the actors.]
    cli & api & mcp & ui & dist & actor & ledger --> ship[Reconcile + guard + tag + push]

Internal Actor Embodiments

The five actor roles in the public skill are concepts. In this repo, each one has a concrete embodiment: a route, a lib module, a fleet persona, and a status surface. When you edit any one of these, you are editing a piece of the actor's body, and the corresponding inboxes, contracts, and operator surfaces must stay coherent.

Actor	Route	Lib module	Fleet persona	Status surface
Coxswain	routes/claims.ts, routes/locks.ts	lib/claims/, lib/locks/, lib/symbol-index/	agents/coxswain.yaml (when present)	claim density + lock health in pd briefing
Navigator	routes/sessions.ts, routes/recovery.ts	lib/sessions/, lib/salvage.ts	agents/navigator.yaml	docs/recovery/CURRENT-WORK.md
Cartographer	routes/cartographer.ts	lib/roadmap-progress.ts, lib/feedback.ts	agents/cartographer.yaml (also lives at .claude/agents/cartographer/)	.cartographer/status.md, IDEAS-TROVE.md, DOGFOOD-FEEDBACK.md
Lookout	routes/lookout.ts	release-surface scanners under lib/	fleet/documentarian.sh (current shell-script form)	drift reports posted to lookout inbox
Quartermaster	routes/spawn.ts, routes/fleet.ts	lib/spawner.ts, lib/cost-tracker.ts, lib/backend-readiness.ts, lib/resource-governance.ts	agents/quartermaster.yaml	spawn budget + readiness in FleetBar

Shipwright is a sixth, internal-only role: it owns skill-bundle ingestion, archetype classification, and survey aggregation across the fleet. Lives at lib/shipwright/{archetypes.ts, skill-index.ts, survey.ts} and routes/shipwright.ts. Tests under tests/unit/shipwright-*.test.js. Don't expose Shipwright in the public skill — it's a port-daddy-internal abstraction.

Release-Surface Drift (the contributor's prime directive)

When Port Daddy itself ships, the cost of inconsistency lands on every project on the user's machine. Every change to a public surface MUST update every mirror in the same coherent slice.

For the actual release ceremony (tagging, GitHub Release, release.yml, brew tap roll via publish.yml), follow docs/RELEASING.md. For semver policy and the canonical list of version surfaces that must all bump in lockstep, see docs/VERSIONING.md.

The list below is the broader surface area a contributor touches before the release ceremony fires — the docs, examples, manifests, and CLI help that lie about behavior if not updated alongside the code.

Public surfaces, in approximate update order:

1. Source code (lib/, routes/, mcp/, apps/FleetBar/).
2. CLI help text (bin/port-daddy-cli.ts and any --help strings touched).
3. The skill bundle (this repo's skills/port-daddy-agent-skill/SKILL.md, references, templates, examples).
4. The website (apps/website-v2/ — /docs/cli, /docs/api, /docs/mcp, command detail routes, screenshots).
5. The OpenAPI spec, SDK reference, MCP tool catalog.
6. README + CHANGELOG + the eight version surfaces in docs/VERSIONING.md.
7. Any plugin/extension manifests (Codex .codex/skills/, Gemini .gemini/extensions/port-daddy/, Claude .claude/skills/).
8. Binary smoke-test (per RELEASING.md §3) for any change in lib/, routes/, server.ts, or mcp/. Source-mode tsx server.ts lies about what users actually run.

The Homebrew formula is no longer a per-PR concern — it rolls during the release ceremony via the curiositech/homebrew-tap repo and publish.yml. See RELEASING.md §1 step J.

If you cannot land all of these in one commit, leave a pd actor lookout message naming the gaps and link the follow-up issue. Lookout is the role that watches for release-surface drift; making the drift visible is your job, fixing it is theirs (or future-yours).

PR Finish Line Discipline

For Port Daddy repo PRs, local validation is not the finish line. Before calling a branch ready, inspect and close the full PR surface:

• Inline bot comments from Copilot, Claude review, Cloudflare Pages, CodeQL, package/release jobs, or deploy previews count as review findings. Reply to each actionable thread with fixed / deferred / contested-because.
• Run a skeptical reviewer agent for non-trivial changes and require a SHIP / SHIP-AFTER-FIX / DO-NOT-SHIP verdict. Fix high-confidence findings as named fixup commits on the branch.
• Treat GitHub CI, external deploy checks, release-package jobs, and Cloudflare Pages as one CI/CD surface. If one is red, inspect the linked logs. Only call it external after proving the branch is not the cause, and record that proof in both the PR and a pd note.
• Do not leave a PR with "CI green except..." as an unresolved aside. Either make it green, file/assign the external blocker with evidence, or hand off the exact next action to an active Port Daddy session.

PR Lifecycle (Create / Update / Land)

The Finish Line Discipline above is the review contract; this is the mechanical contract. AGENTS.md (## Pull Request Operating Procedure) carries the canonical copy — this is the contributor-repo mirror.

Create. Linked worktree off origin/main under ~/coding/tmp/wt-<slug> (never the main checkout — it carries the operator's WIP) → pd begin "<purpose>" --identity port-daddy:contrib:<slug> → scope pd note → pd session files add <files> before editing → edit → pd guard check --staged → commit (no Claude co-author trailer) → git push -u origin <branch> → gh pr create → pd done.

Update (review + CI). Pull bot comments with gh api repos/curiositech/port-daddy/pulls/<n>/comments and fix the real ones. Land every HIGH adversarial finding as a named fixup commit. Get npx tsc --noEmit, jest, npm run parity, and the build green. Rebase onto latest origin/main, resolve conflicts, push.

Land. Merge in dependency order: base before dependent, and rebase the dependent after each merge — mergeability can flip MERGEABLE → CONFLICTING the moment the base lands. gh pr merge <n> --squash --admin. --admin is correct: it bypasses the BEHIND/up-to-date gate AND the Cloudflare Pages check. Cloudflare Pages is an external gate (Pages build pipeline, not repo CI) that always fails on PRs and is never a merge blocker.

Cleanup. Delete a worktree only when its branch is merged AND git -C <wt> status --porcelain is clean. Never delete a worktree with uncommitted work; never reset or clobber the main checkout.

Shell gotchas (real and recurring)

• git add -A is refused by the pd-shim. When you truly mean all (rare; prefer explicit paths), use PD_SHIM_OFF=1 git add so the bypass is deliberate.
• The ~/.port-daddy/bin/git shim sets core.pager=delta → bat. If bat is absent, git log / git show / git commit emit command not found: bat and can swallow output. Use git -c core.pager=cat … or GIT_PAGER=cat.
• Inline node -e and heredocs get mangled by zsh. Write a .cjs under the repo's .scratch/ (gitignored, resolves node_modules) and run it.
• Secrets go through pd secret set (hidden stdin prompt) — never as an argv argument.

Distribution Mirror Sync

The skill bundle is mirrored to several locations. Inside this repo the canonical copy is skills/port-daddy-agent-skill/. The metadata.mirrors block in its frontmatter declares targets:

Target	Purpose	Sync trigger
.codex/skills/	Codex CLI agents on this repo	install.sh + brew post_install
.claude/skills/	Claude Code agents on this repo	install.sh + brew post_install
.agents/skills/	Generic AGENTS.md-aware tools	install.sh
.gemini/extensions/port-daddy/skills/	Gemini CLI extension surface	install.sh
windags-skills (out of repo)	Public catalog distribution	manual cp -r from this repo to ~/coding/windags-skills/skills/

port-daddy-internal-dev (this skill) is intentionally absent from the mirrors-list above. Do not propose distributing it. Its presence on a non-port-daddy machine would be confusing noise.

Recovery Ledger Discipline

docs/recovery/CURRENT-WORK.md is owned by Navigator + Cartographer. Do not edit it directly. Send messages to those actors:

pd actor navigator --message "ROADMAP: <slice> completed at <commit>. Suggest promoting next: <item>."
pd actor cartographer --message "DOGFOOD: <synthesis>. Suggest roadmap entry: <name>."

Mailbox delivery is durable but not synchronous. After messaging an actor, keep working from the actual source of truth: docs/recovery/CURRENT-WORK.md, .cartographer/README.md, .cartographer/status.md, live notes, sessions, and the checked-in release surfaces.

If docs/recovery/CURRENT-WORK.md contradicts the live fleet, that is a Navigator issue. File it; do not silently overwrite.

Git Discipline (inherited; see ADR 0001)

The five rules from port-daddy-agent-skill apply here too — and harder, because this repo has the highest agent density on the user's machine.

1. Worktree mandatory for any background contributor work — even small ones. The repo has 70+ existing worktrees and dozens of WIP branches; sweeping up someone's WIP is a near-certainty without isolation.
2. No git add -A ever. No exceptions. The repo has too many drafts in flight.
3. Pre-commit git status --porcelain check. Abort on foreign files. The pre-commit hook from pd guard install --mode enforce should be on at all times in this repo.
4. Lock the staging area if you must work in the main checkout: pd lock port-daddy:git:write (or pd with-lock port-daddy:git:write -- <command>). MCP-aware clients can call acquire_lock with the same name.
5. Push only what you tagged. Never git push --follow-tags from a contributor agent.

See references/git-discipline-internal.md for port-daddy-specific extensions (release-tag immutability, the v-prefix convention, the brew formula update protocol).

Catalog-First Reflex (windags MCP, internal edition)

Port Daddy contributors are not exempt from the catalog. The 600+ skills in ~/coding/windags-skills/ cover most patterns you'll hit while editing this codebase: rate limiting, caching, websocket protocols, distributed transactions, pre-mortems, evaluation harnesses, design systems for the website, and more.

windags_skill_search "<the thing you're about to do>"
windags_skill_graft <skill-id> [skill-id...]

Before every contributor slice, one search. Examples that have paid off:

• Editing the daemon's lock-acquire path? windags_skill_search "distributed lock semantics" → grafts distributed-algorithms and sagas-garcia-molina-salem-1987.
• Adding a new MCP tool description? windags_skill_search "MCP tool description writing" → grafts mcp-creator if relevant.
• Touching the website? windags_skill_search "responsive layout master" and friends — the design-system skills ship with usable component patterns.
• Writing pre-release tests? windags_skill_search "adversarial QA" → grafts qa-automation-specialist or webapp-testing.

If the catalog is wrong or stale for our domain, that's a Cartographer issue: pd actor cartographer --message "Catalog gap: <what skill should exist>. Use case: <internal slice>."

Maintain These Skills (port-daddy-internal-dev edition)

This skill is alive. It improves when contributors update it. When you finish a slice — any slice on this repo — ask: did I just learn something that this skill or port-daddy-agent-skill should have warned me about?

Contributors are the only agents who write to both surfaces. As an internal agent you own a continuous maintenance duty for both:

• Public (skills/port-daddy-agent-skill/SKILL.md) — anything that helps an agent on any project using Port Daddy. New verb, deprecated flag, decision row, anti-pattern, clarification, brevity win.
• Internal (this skill) — anything specific to editing this repo: release ceremony, internal actor embodiments, drift protocol, worked contributor examples.

Drive-by edits are explicitly welcome on both. No issue required, no permission required. Same-slice fixes — landing the skill update alongside the code change that revealed the problem — are the default; that is what keeps the documentation from going stale between releases. Retrospective edits (the lesson surfaced days later) are still owed; open a tiny PR.

Concrete triggers:

• You hit a release-surface gap the protocol didn't cover. Update references/release-surface-drift-protocol.md.
• An internal actor's body moved (new route, lib reshuffle). Update the Internal Actor Embodiments table.
• A worked example would have saved an hour for a recurring slice. Add it to examples/.
• A new useful internal-only tool (audit script, fleet persona, debugger) was written. Cross-link from this skill.

Update mechanics:

git worktree add ../port-daddy-internal-skill-$(date +%s) origin/main
cd ../port-daddy-internal-skill-*
pd begin "Update port-daddy-internal-dev: <what>" --identity port-daddy:contrib:internal-skill-update
$EDITOR skills/port-daddy-internal-dev/SKILL.md   # or references/<file>.md
git add skills/port-daddy-internal-dev/<paths>
git status --porcelain                             # must be clean of foreign files
git commit -m "skill: port-daddy-internal-dev — <change>"

If the wisdom is public (any agent on any project would benefit), put it in port-daddy-agent-skill instead. The split-decision rule: would this help an agent on a non-port-daddy repo? Yes → public. No → internal. Both? → public, with a port-daddy-specific extension page in this skill.

After landing, send Cartographer: pd actor cartographer --message "port-daddy-internal-dev updated: <section>. Reason: <session/incident>."

Operating Loop (contributor)

# 1. Anchor + reconnaissance
pd status
pd briefing
pd salvage --project port-daddy --limit 20
pd sessions --all-worktrees

# 2. Worktree (always)
git worktree add ../port-daddy-$(date +%s)-$WORK_SLUG origin/main
cd ../port-daddy-$(date +%s)-$WORK_SLUG

# 3. Identity and scope
pd begin "<bounded slice>" --identity port-daddy:contrib:$WORK_SLUG
pd note "Scope: <surfaces>. Assumptions: <truth>. Validation: <commands + tests>."
pd session files add <path>...

# 4. Work
# ... edits ...

# 5. Reconcile
git fetch origin
git rebase origin/main
pd notes --limit 20
pd guard check --staged

# 6. Cross-surface coherence (the contributor-specific bit)
node scripts/release-surface-audit.mjs   # if present
# OR walk the Release-Surface Drift list above by hand

# 7. Commit + push (NOT tag — tags are release work, see RELEASING.md §1)
git add <explicit paths>
git status --porcelain          # MUST be clean of foreign files
git commit -m "<scope>: <change>"
git push -u origin <feature-branch>
gh pr create ...                # standard PR flow

# 8. Close
pd note "Result: <change>. Validation: <evidence>. Remaining: <Lookout drifts, follow-ups>."
pd done "<outcome>"
pd feedback "<contributor experience report>"   # bare form; auto slug + agent

For releases (cutting v3.X.Y, building binaries, rolling the brew tap): follow docs/RELEASING.md, not this loop. Tagging here is a footgun — feature branches must not push tags. The "binary smoke-test before merging anything in lib/, routes/, server.ts, or mcp/" rule is in RELEASING.md §3; honor it.

Anti-Patterns (port-daddy contributor edition)

Editing The Recovery Ledger Directly

Detection: Diff includes docs/recovery/CURRENT-WORK.md without a Navigator message in the same slice. Symptoms: Live fleet contradicts the ledger; salvage routes to wrong sessions; Cartographer status falls out of sync with reality. Fix: Always route ledger updates through pd actor navigator or pd actor cartographer. The actor is the writer of record. Why: The ledger is the audit trail. Direct edits are silent rewrites of audit history.

Bumping One Surface, Forgetting Six

Detection: A pd ... command's behavior changed; CLI help is current; website /docs/cli/<command> page is stale; OpenAPI is stale; skill references/cli-reference.md is stale. Symptoms: Operators read four different versions of "what does this command do" depending on where they look. Lookout inbox fills. Fix: Walk the Release-Surface Drift list before commit. If you can't update all of them in this slice, send pd actor lookout a message naming the gaps with a link to the follow-up. Timeline: Single-surface tools could ship one update at a time; Port Daddy spans CLI + daemon + MCP + website + Mac app + skill bundle + brew. Each new surface compounds the drift cost.

Treating Shipwright As Public

Detection: Shipwright concepts (archetype classification, skill-index aggregation, survey rollups) appear in port-daddy-agent-skill or references/actor-roster.md. Symptoms: Users on other projects see internal abstractions in their docs; the public skill bloats; Shipwright's contract leaks before it stabilizes. Fix: Keep Shipwright references in this skill (port-daddy-internal-dev) only. The public surface should expose its outputs (better skill matches, better classifications) without naming the internal mechanism.

Force-Pushing A Release Tag

Detection: A vX.Y.Z tag points to a different commit than the one originally tagged. Symptoms: Brew formulas with frozen sha256 break for users; CI caches invalidate; users on the old tag see different code than users on the new one with the same tag string. Fix: Tags are immutable. If a release was wrong, ship vX.Y.Z+1 with a CHANGELOG entry explaining the recall. Never git push --force origin vX.Y.Z.

Skipping pd feedback On Contributor Friction

Detection: Internal contributor sessions end clean but the friction isn't recorded; the same friction visits the next contributor. Symptoms: "Why is this so hard" gets discovered repeatedly. The roadmap doesn't reflect the actual pain. Cartographer's priorities lag reality. Fix: End every contributor session with pd feedback "<one-liner>" (bare form) or drop_feedback({ slug, summary, droppedBy }) from MCP, even (especially) if everything went smoothly — record what worked too. Friction patterns and frictionless patterns are both signal.

Worked Examples

Example 1: Adding a new MCP tool

Slice: Add pd_swarm_status MCP tool that returns aggregate fleet health.

1. Worktree: git worktree add ../port-daddy-$(date +%s)-mcp-swarm-status origin/main && cd $_.
2. pd begin "Add pd_swarm_status MCP tool" --identity port-daddy:contrib:mcp-swarm-status.
3. Implement in mcp/server.ts (new tool registration).
4. Implement the underlying lib in lib/swarm-status.ts if not present.
5. Update scripts/mcp-handshake-test.mjs — bump REQUIRED_TOOLS count and assert.
6. Update port-daddy-agent-skill/SKILL.md "MCP Equivalents" list.
7. Update website apps/website-v2/.../mcp-catalog.tsx (or equivalent route).
8. pd actor lookout --message "NEW MCP TOOL pd_swarm_status: tested, surfaces updated."
9. Commit with explicit paths; tag if this is part of a numbered release.

Example 2: Renaming an internal actor

Slice: Rename Lookout to Watchstander.

This is enormous: it touches the public skill, this skill, every reference, every actor message ever sent, the website, the CLI, the MCP. Do not do it in one commit. Land the rename in phases through Cartographer:

1. pd actor cartographer --message "PROPOSAL: rename Lookout → Watchstander. Scope spans 12+ surfaces. Suggest milestone breakdown."
2. Wait for Cartographer to publish the milestone breakdown.
3. Land aliases first (both names work; Lookout is deprecated).
4. Migrate one surface per slice with Lookout's drift discipline.
5. Cut the Lookout name only after the public skill, website, and brew formula have shipped two consecutive versions with the alias.

Example 3: Bumping the brew formula

Slice: Ship v0.42.0.

1. Worktree, identity, scope note.
2. Tag locally: git tag -a v0.42.0 -m "<changelog summary>".
3. Compute tarball sha256: curl -sSL <github tag tarball> | shasum -a 256.
4. Update the in-repo primary Formula/port-daddy.rb: url, sha256, version-string-in-tests if present, post_install if install.sh changed. Then mirror the same change into the external tap repo (homebrew-port-daddy/Formula/port-daddy.rb) — both must match before the brew install command in step 5 will succeed for users.
5. brew install --build-from-source ./Formula/port-daddy.rb locally; confirm install path, daemon launches, pd status healthy.
6. pd actor lookout --message "Brew formula v0.42.0 ready: <sha256>. Surfaces audited: README, CHANGELOG, website, skill bundle."
7. Push the tag from port-daddy first, then commit + push the formula.

Quality Gates (contributor)

• You worked in a worktree (not the main port-daddy checkout).
• You ran pd guard check --staged; it passed cleanly.
• You staged by explicit path; git add -A does not appear in your shell history for this slice.
• Every public surface affected has been updated in this slice OR a Lookout message names the gap.
• If you touched an internal actor's body, you updated the actor-roster reference and the matching decisions/ entry.
• If you renamed or removed a CLI / API / MCP surface, you provided a migration path and a deprecation window.
• You did not edit docs/recovery/CURRENT-WORK.md directly.
• You ended with pd done AND pd feedback "..." (CLI bare form) or MCP drop_feedback.
• If you skipped any of the above, you owned up to it explicitly in the feedback.
• You ran windags_skill_search for the slice's domain before starting.
• Two-skill maintenance check. You asked: "did the public port-daddy-agent-skill or this internal skill mislead me, mis-instruct me, or under-equip me?" If yes, you landed the fix on the correct surface (public vs. internal — see "Maintain These Skills") in the same slice. Drive-by edits are explicitly welcome; no separate ticket required.
• You did NOT propagate internal-only wisdom into port-daddy-agent-skill (that's the public skill's split-decision rule).

Sources

• ADR 0001 — Background-Agent Git Discipline.
• port-daddy-agent-skill/SKILL.md — public companion this skill extends.
• lib/shipwright/ — internal skill-bundle ingestion + classification (the contributor-facing "Shipwright" concept).
• routes/cartographer.ts, routes/spawn.ts, routes/sessions.ts — actor route ownership.
• references/release-surface-drift-protocol.md (this skill) — the full mirror-update walk.
• references/git-discipline-internal.md (this skill) — port-daddy-specific git extensions.