v2.0.0 — Plugin distribution

Distribution milestone: SwiftShip installs as a Claude Code plugin

/plugin marketplace add rshankras/claude-code-apple-skills
/plugin install apple-skills@indie-apple-stack
/plugin install apple@indie-apple-stack

No breaking changes — every /apple:* command name, template tag, and .planning/ schema is unchanged (the major version marks the distribution-model shift, not a compatibility break). Manual clone + install.sh remains fully supported as the contributor/dev path.

Added

• Plugin distribution — SwiftShip is a Claude Code plugin (apple@indie-apple-stack), updatable via /plugin marketplace update. Command names preserved byte-identical: the plugin is named apple (displays as SwiftShip in the plugin browser) and commands/apple/*.md moved to flat commands/*.md, so the plugin namespace supplies the same /apple:* prefix the directory name used to.
• Plugin hooks/hooks.json (plugin installs only): a SessionStart glue script maintains the ~/.claude/swiftship-templates and ~/.claude/swiftship-skills symlinks — guarded so a symlink to a real checkout is never overwritten — plus the usage-log hook (local-only ledger on by default for plugin installs, disclosed in the README; manual installs stay opt-in).
• Agent types are namespaced in plugin installs (apple:swift-generalist): spawning commands and the AGENT-VENDORING degraded-mode guard document the bare-name → prefixed retry across all three install modes.
• scripts/validate.sh plugin checks (manifest parses; plugin name must be apple — it IS the command namespace) and a plugin-validate CI job.
• Fixing plugin validation surfaced real YAML defects the lenient runtime parser had masked: all six agents' multi-line descriptions are now proper block scalars; autonomous.md's argument-hint quoted.

Compatibility

Tested against claude-code-apple-skills main @ aa13bcc (2026-07-04), which includes the indie-apple-stack marketplace with the SwiftShip entry (HTTPS source, displayName: SwiftShip) and the apple-skills plugin (23 category skills). Requires the apple-skills plugin (or a skills checkout + install.sh) for skill references to resolve.

v1.1.0 — model right-sizing and resilience

Model right-sizing and resilience: the first release shaped by the usage
ledger — every change below traces to a measured finding, not a hunch.

Added

• ./install.sh --uninstall — removes only SwiftShip's symlinks (commands,
  per-file agent links, templates, skills, hook script); never touches the
  user's own agents, settings.json, the usage ledger, or project
  .planning/ files. README gains matching Updating and Uninstall
  sections plus a three-command from-zero quickstart (the committed
  install.sh is already executable — the chmod step was noise).

• Agent vendoring (templates/_conventions/AGENT-VENDORING.md): /apple:new-app
  and /apple:map offer to copy SwiftShip's six pinned agents into the target
  project's .claude/agents/ — project-level agents outrank user-level and
  travel with git, so cloud/CI/remote-launched sessions keep the Sonnet pin
  and the full review gate. Includes a .swiftship-agents marker for
  stale-copy refresh, and a degraded-mode guard in /apple:build +
  /apple:review: when agents can't spawn, the command must say so, ask
  before proceeding, banner review output as DEGRADED, and log
  "degraded":"no-agents" (review: outcome: "partial") — observed in the
  wild as a remote session silently substituting a 3-minute self-review for
  the 8-agent verified gate. Vendoring and the guard also call out that agent
  definitions load once at session start: copies vendored mid-session can't
  spawn until a restart, so new-app/map say so on acceptance (observed as
  a spike falling back to general-purpose right after vendoring).

• Model-tier convention (templates/_conventions/MODEL-TIERS.md): maps every
  command to a recommended session model tier — judgment (Fable-class:
  validate, roadmap, debug…), analysis (Opus-class: map, security, metadata…),
  execution (Sonnet-class: build, review, ship…) — on the principle that
  strategy is token-cheap but consequence-expensive while execution is the
  reverse (agents are Sonnet-pinned regardless). plan, build, review
  print a one-line note when the session model is off-tier (never blocking);
  autonomous asks once before a long run. Compliance is measured via the
  usage ledger's model field.

• Usage ledger: optional model field on "outcome" lines — records which
  session model a workflow command ran on (subagents are always Sonnet), so
  /apple:usage can analyze cost per command.

• Task-level model routing: /apple:plan may tag at most 1–2 foundation
  type="auto" tasks per phase with model="opus" (architecture, data model,
  concurrency, migration — mistakes that propagate into everything built
  after them); /apple:build passes the tag through as the agent spawn's
  per-call model override. An absent tag means the Sonnet frontmatter pin,
  so existing PLAN.md files are unaffected (additive schema). Escalated
  spawns land in the usage ledger's agents object as "agent:opus" keys so
  /apple:usage can test whether escalation actually reduces review findings
  and verify failures. Haiku downshift is deliberately withheld pending that
  evidence. Mechanism + rules live in MODEL-TIERS.md ("Per-spawn overrides").

• /apple:usage — reads the local usage ledger into a report: command mix
  (invocations vs completed runs), outcome/blocker rates, model-tier
  adherence against MODEL-TIERS.md, and escalation economics (agent:opus
  spawns vs review findings). Rule-based recommendations only — including the
  explicit gate that Haiku downshift stays withheld until ≥10 datapoints show
  mechanical tasks never failing verification. Read-only, local-only, prints
  no dollar figures (prices drift; the command must not rot), and — as an
  info command — logs nothing itself.

Changed

• Execution-tier hot-loop commands (build, review, verify, test,
  bugfix, ship) now pin model: sonnet in command frontmatter. The
  override is turn-scoped (documented Claude Code behavior: the command's
  turn runs on the pinned model, the session model resumes on the next user
  prompt), so it can never downgrade a later judgment-tier command, and
  per-spawn Opus escalation (Task-call model parameter) still outranks it.
  Replaces the "remember to /model sonnet" habit the first /apple:usage
  report showed wasn't happening: 10/10 execution-tier runs in the ledger
  billed premium main-loop rates (fable-5 ×5, opus-4-8 ×5) for routing work
  the Sonnet-pinned agents did anyway. The printed tier note remains as
  fallback for installs predating the pin and org model allowlists that
  exclude Sonnet; /apple:autonomous stays unpinned (its main loop includes
  plan-phase judgment work) and keeps its ask-once gate.

• /apple:review Critical-finding verifiers now escalate to Opus via a
  per-spawn model override (High verifiers stay on the Sonnet pin). A
  Sonnet verifier checking a Sonnet reviewer shares its blind spots, and a
  wrong verdict either pauses /apple:autonomous (false Critical) or ships a
  real bug (false confirm) — the few Opus spawns per review are the cheapest
  rigor in the pipeline. Falls back to the pin (with an audit note) if the
  escalated spawn fails.

Fixed

• Degraded-mode guard now catches agent substitution, not just spawn
  failure: swapping the built-in general-purpose in for the named agents
  triggers the same ask + DEGRADED banner + "degraded":"no-agents" ledger
  fields — observed in the wild as a review that ran general-purpose:sonnet
  ×8 (no hig-reviewer/app-store-reviewer) yet logged a clean completed,
  indistinguishable from the full gate except via spawn keys. Per-call
  model overrides on substitute spawns are kept (they preserve the cost
  pin) but don't make a run non-degraded. /apple:usage now cross-checks
  spawn keys against the degraded field and reports bypassed guards.

• install.sh no longer replaces the user's entire ~/.claude/agents/
  directory with a symlink — the six agents are now linked per-file, so
  any agents the user already has keep loading alongside SwiftShip's.
  Previously an existing agents directory was shunted to agents.backup and
  silently deactivated — an adoption-killer for exactly the audience most
  likely to try SwiftShip. Legacy whole-directory installs are migrated
  automatically on the next ./install.sh run (with a note when an
  agents.backup exists to restore from); --uninstall handles both layouts.

• /apple:build task→agent table gains an explicit catch-all row (anything
  unmatched → swift-generalist) and an in-command prohibition on the built-in
  general-purpose agent; the same guard added to /apple:review and
  /apple:test. The rule previously lived only in this repo's CLAUDE.md, which
  target projects never load — first day of ledger data showed Phase-1 builds
  spawning general-purpose at session-model rates.

• /apple:ship now uses the ASC MCP for steps it previously punted to the
  user: a new Step 2 creates the App Store version via create_version when
  missing (it was in allowed-tools but never referenced), Step 3 pushes
  What's New from .planning/RELEASE-NOTES.md via update_whats_new, and
  Step 7 offers a phased release via create_phased_release — all
  preview → confirm → apply.

• TOOL-HANDOFF.md clarifies that "manual is the default" means the manual
  path always exists — not that it's suggested first; a detected tool is the
  primary path.

• Usage hook now captures user-typed /apple:* commands. Slash commands are
  expanded client-side and never reach the Skill tool, so the previous
  PostToolUse-only registration missed them entirely; the hook is now also
  registered on UserPromptSubmit (same script handles both input shapes).

• USAGE-LOG.md outcome example now stamps ts via $(date -u ...) instead
  of a hardcoded literal — prevents placeholder timestamps (e.g. midnight)
  landing in the ledger when the model doesn't know the current time.

• Adversarial verification ("foreman") step in /apple:review: every
  Critical/High finding is verified against the actual code before it reaches
  REVIEW.md — 2 independent verifiers per Critical (both must confirm; a
  split verdict downgrades to High), 1 per High; findings without a
  file:line are downgraded to Medium as unverifiable. Refuted claims are
  preserved in a "Refuted During Verification" appendix for audit. Protects
  /apple:autonomous from pausing on false Criticals.

Compatibility

• Tested against claude-code-apple-skills main @ a0226e8 (2026-07-04,
  plugin-marketplace distribution); all skill references resolve via
  ~/.claude/swiftship-skills/ unchanged — CI validates against this repo
  on every PR.

SwiftShip v1.0.0

First stable release. main remains the development channel; tags are the stable channel.

Highlights

• The workflow: spec-driven pipeline from idea to App Store (/apple:brainstorm → validate → new-app → roadmap → plan → build → review → submit), a brownfield entry for existing apps (map → release), and /apple:autonomous to drive plan → build → verify unattended
• 48 commands covering build & quality, planning & product, and App Store & growth — including the ASC finalizers (iap, privacy), the one-command final mile (ship), and post-launch learning (learn-from-store, experiment)
• 6 specialist agents, all pinned to Sonnet — including swift-generalist, which enforces the model in frontmatter so workers never silently inherit expensive session-model rates
• 140+ skills wired in from claude-code-apple-skills
• Optional tool handoffs (detect → preview → confirm → act → fall back): ASC metadata/TestFlight push, simulator run & screenshot, read-only sales feeds — manual path always the default, graceful with zero tools installed
• CI on every PR: scripts/validate.sh checks that all skill/template references resolve, counts match reality, commands are registered, and frontmatter is well-formed
• Local-only usage ledger (opt-in) for data-driven improvement — nothing leaves the machine

Compatibility

Tested against claude-code-apple-skills main @ 25a618b (2026-07-02), which includes the macos/*/SKILL.md case fix (rshankras/claude-code-apple-skills#15) required on case-sensitive filesystems.

Full details in CHANGELOG.md.