docs: prefer isolated pod over dev-backend.sh for worktree preview

[bolichen97]

Problem / Motivation

Rule 5 of the kirocrew-worktree-dev skill listed ./dev-backend.sh and the
isolated pod (kirocrew pod up) as two equally-weighted preview options for a
worktree. In practice the pod needs no cleanup discipline of its own (own port,
own KIROCREW_HOME, zero residue on pod down), while dev-backend.sh leaves
a foreground process and a .kirocrew-dev/ directory the developer manages by
hand — but nothing in the skill said which to reach for by default.

Why it matters

A contributor (human or agent) following this skill has no signal for which
preview path is the better default, so they either pick arbitrarily or default
to whichever is listed first (dev-backend.sh), which is the less hands-off
option for the common case.

What changed (motivation → approach → change)

Goal: make the pod the default preview path without removing dev-backend.sh,
since it is still needed on hosts without systemd --user / launchd, or when
a foreground process is specifically wanted for attaching a debugger.

• Rule 5: reordered so the isolated pod is option 1 (preferred), with a new
  sentence stating the preference and why, plus a note on the platform gate
  (systemd --user / launchd) linking to kiro_crew/pod/README.md.
• dev-backend.sh is now option 2, explicitly framed as the fallback for hosts
  without that platform gate, or when a foreground/debugger-attachable process
  is specifically needed.
• Frontmatter description reordered to match ("isolated pods, dev-backend.sh
  as fallback").

Tests

Docs-only change; no automated tests apply. ./scripts/docs-lint.sh was run
(see Manual verification) rather than added to, since it already covers
markdown structure/link checks repo-wide.

Manual verification

• ./scripts/docs-lint.sh passes: 259 markdown files scanned, no new issues.
• Read through the rendered Rule 5 section manually to confirm the numbered
  list, code blocks, and the new relative link (../../../pod/README.md)
  resolve correctly from src/kiro_crew/builtin_skills/kirocrew-dev/kirocrew-worktree-dev/SKILL.md.

Related Issues

N/A — no tracking issue; raised directly from internal usage feedback.

Pattern harvest

Not generalizable: this is a one-off reordering of prose/example precedence in
a single skill file, not a defect class.

Checklist

• At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|refactor|perf|test|chore|ci|build|revert: ...)
• Existing tests pass and new tests added for new functionality — N/A, docs-only
• Self-review completed; code follows project style guidelines
• Documentation updated (if applicable) — this PR is the documentation update
• No secrets, credentials, or internal references in the diff

[github-actions]

Opus 4.8 Review (fork) — ✅ no blocking findings

Reviewed bba402515c3c883ee7197cb8b4ac412e24244a58 via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] bba4025

[github-actions]

Design Review (Fable 5, fork) — 🟡 CONCERNS

Design-level review of bba402515c3c883ee7197cb8b4ac412e24244a58 via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: CONCERNS

The preference is sound, but the new claim links to a README whose Platform section asserts the exact opposite — "Linux systemd --user only."

Watch

• The diff adds "Pods need Linux systemd --user or macOS launchd … see kiro_crew/pod/README.md for the platform gate", but that README's Platform section (line 221) still reads "Linux systemd --user only… Use ./dev-backend.sh to preview a worktree on this platform [darwin]." The code agrees with the skill (pod/launchd.py is a full backend, runtime.require_backend dispatches on IS_MACOS), so the README is stale — yet the PR now cites it as the authority, sending a macOS reader to text that refutes the skill's new default and steers them back to dev-backend.sh. Update the README's Platform section in this same PR, or the guidance defeats itself on the platform it just claimed to add.

Suggestions

• Drop or qualify "(kirocrew pod install once per machine)" — install_backend is an explicit no-op on macOS ("nothing to install on macOS… each pod's agent plist is written at pod up"), so the parenthetical is Linux-only.

[DESIGN-REVIEWED] bba4025

[github-actions]

GPT 5.6 Review (fork) — ✅ no blocking findings

Reviewed bba402515c3c883ee7197cb8b4ac412e24244a58 via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] bba4025

[github-actions]

First Principles Review (Fable 5, fork) — 🟡 CONCERNS

Premise-level review of bba402515c3c883ee7197cb8b4ac412e24244a58 via the fork AI-review pipeline — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

I have everything I need. The key facts: the pod's launchd backend exists in code (src/kiro_crew/pod/launchd.py), but the linked pod/README.md § Platform still says "Linux systemd --user only" and quotes a darwin refusal message — so the patch's new restated platform sentence contradicts the very doc it cites. And runtime.py:1514 says pod install is "nothing to install on macOS", contradicting the patch's "kirocrew pod install once per machine" for the launchd half. The grep for dev-backend across *.md also shows two other spots still listing dev-backend.sh first.

First-Principles-Verdict: CONCERNS

The preference flip is earned, but the new platform-gate sentence restates a gate its own cited README contradicts, and two sibling docs still list dev-backend.sh first.

What this change ships

Intent: make the isolated pod the default worktree-preview path in the dev skill, demoting dev-backend.sh to fallback — a REORDER of existing guidance, no new capability.

1. Pod listed first with an explicit "prefer" sentence — justified; properties (zero residue, own home/port) already documented in the base file.
2. dev-backend.sh relabeled fallback with named conditions — justified, declared.
3. New restated platform-gate sentence + link to pod/README.md — second spelling, diverges from its source at birth.
4. Frontmatter description reordered to match — declared, consistent.

Watch

• The restated gate is wrong on both halves. The new sentence says "Linux systemd --user or macOS launchd (kirocrew pod install once per machine)", but the README it links "for the platform gate" says "Linux systemd --user only" and quotes a darwin refusal pointing at dev-backend.sh (pod/README.md:221-226); the code says install is a no-op on macOS ("nothing to install on macOS", pod/runtime.py:1514). Whichever copy is current, two prose copies of one gate now exist and already disagree — the exact stale-restatement failure AGENTS.md names.
• Point patch, 2 counted siblings (grepped dev-backend over *.md): Rule 6 of the same file (SKILL.md:306) and web-verify/SKILL.md:83 still name dev-backend.sh before pods. The in-file Rule 6 sibling was reachable in this change's scope.

Subtractions

• Shrink item 3 to the pointer alone: drop the restated backend list and the pod install parenthetical, keeping "pods have a platform gate — see pod/README.md; where the pod verbs refuse, fall through to dev-backend.sh". The refusal message itself already routes the user.

[FIRST-PRINCIPLES-REVIEWED] bba4025

[bolichen97]

Open PR relationship audit

This is a consolidated, point-in-time code-level audit note. It compares complete merge-base diffs and current/merged code; it does not treat a shared topic as duplication or partial coverage as completion.

Relationship findings

• PR #8223 is OVERLAPPING relative to this PR. The goals differ or the implementations can complement each other; this is not a duplicate claim. Recommended action for PR #8223: MERGE_DISCUSSION. Complementary and non-conflicting: the merged PR sets up the preview path this PR turns into a proof step. Files: src/kiro_crew/builtin_skills/kirocrew-dev/kirocrew-worktree-dev/SKILL.md.

No PR, Issue, label, branch, or review state was changed by the relationship-note portion of this audit.