@jenga-ai/agent 1.0.0

package/skills/publish/SKILL.md

@@ -0,0 +1,351 @@
+---
+name: publish
+description: Configure, validate, and orchestrate scaffolded release workflows through a single `/publish` entry point with bounded sub-commands.
+keywords:
+  - publish
+  - deploy
+  - release
+  - app store
+  - npm
+  - registry
+  - release notes
+examples:
+  - "publish setup --target staging-appstore"
+  - "publish setup --type mobile-ios"
+  - "publish setup --type npm"
+  - "publish deploy --target staging-appstore --yes --dry-run"
+  - "publish deploy --target npm-registry"
+  - "publish deploy --target npm-registry --dry-run"
+  - "publish setup --type droplet"
+  - "publish deploy --target my-droplet"
+  - "publish deploy --target my-droplet --dry-run"
+  - "publish history --limit 5"
+  - "publish release-notes --target staging-appstore"
+metadata:
+  scope: multi-target-v2
+  primary_target: multi
+  primary_platform: multi
+  supported_target_types:
+    - mobile-ios
+    - npm
+    - npm-ci
+    - droplet
+---
+
+# Publish — Deployment Pipeline Orchestrator
+
+`/publish` is the single entry point for release workflows in this repository. It wires configuration validation, setup, gated deployment, release-note drafting, and ledger history into one end-to-end flow, and dispatches the final publish step to a per-type adapter.
+
+Four target types are currently supported:
+
+- **`mobile-ios`** — publishes an iOS build to App Store Connect via the iOS adapter. See the [iOS App Store](#ios-app-store) section for iOS-specific configuration.
+- **`npm`** — publishes a package to an npm registry via the npm adapter. See the npm adapter (`skills/publish/adapters/npm.md`) and the npm wizard (`skills/publish/wizards/npm.md`) for npm-specific configuration.
+- **`npm-ci`** — publishes a package to npmjs.com via GitHub Actions OIDC (Trusted Publishers), with no `NPM_TOKEN` stored. The adapter generates a GitHub Actions workflow, commits it to the repository, and triggers it via `gh workflow run`. See the npm-ci adapter (`skills/publish/adapters/npm-ci.md`) and the npm-ci wizard (`skills/publish/wizards/npm-ci.md`) for configuration details.
+- **`droplet`** — deploys a website or app to any SSH-reachable Linux host (including DigitalOcean Droplets) using a generated GitHub Actions workflow. The workflow SSHes into the host, pulls the deploy branch, runs an optional build command, and restarts the service. See [Droplet (GitHub Actions → SSH)](#droplet-github-actions--ssh) for configuration details.
+
+Every sub-command validates the config before doing anything else, so behaviour is identical regardless of which target type a project uses.
+
+## Invocation Contract
+
+Before any sub-command executes, validate the config with:
+
+```bash
+bash skills/publish/scripts/validate_config.sh <path-to-publish.json>
+```
+
+For deploy-oriented flows, validate the selected target with:
+
+```bash
+bash skills/publish/scripts/check_target_config.sh <target-name> <path-to-publish.json>
+```
+
+- Default config resolution: prefer repo-root `publish.json`, fall back to `project/configs/publish.json`
+- Schema: `skills/publish/schemas/publish.schema.json`
+- Example config: `skills/publish/assets/publish.example.json`
+- Secrets guide: `skills/publish/assets/secrets-guide.md`
+- Deploy contract and exit codes: `skills/publish/assets/ci-contract.md`
+- iOS adapter template: `skills/publish/adapters/mobile-ios.md`
+- npm adapter template: `skills/publish/adapters/npm.md`
+- Ownership matrix: `skills/publish/assets/ownership-matrix.md`
+
+If config or env validation fails, the skill exits with code `4` and does not continue.
+
+## Sub-Commands
+
+| Command | Purpose | Implementation script | Notes |
+|---|---|---|---|
+| `/publish setup` | Prepare or refresh target configuration | `skills/publish/scripts/setup_wizard.sh` | Supported types: `mobile-ios`, `npm`, `npm-ci`, `droplet` |
+| `/publish deploy` | Run the full 11-step deploy orchestration | `skills/publish/scripts/publish_deploy.sh` | Dispatches to the adapter for the target's `type` (`mobile-ios`, `npm`, `npm-ci`, or `droplet`); `--dry-run` is honoured end-to-end |
+| `/publish history` | Read the canonical publish ledger | `skills/publish/scripts/show_history.sh` | Target-agnostic; filter by `--target <name>` |
+| `/publish release-notes` | Generate release notes without publishing | `skills/publish/scripts/generate_release_notes.sh` | Target-agnostic |
+
+## Quality Gate Policy
+
+The deploy flow invokes `skills/publish/scripts/run_gates.sh` at two fixed points:
+
+1. **Pre-deploy:** `run_gates.sh pre <target> <publish.json> [--non-interactive]`
+2. **Post-deploy:** `run_gates.sh post <target> <publish.json> [--non-interactive]`
+
+- `build` and `test` are **mandatory global** pre-deploy gates — always run, cannot be disabled via config
+- Per-target `checks.pre` and `checks.post` can add optional gates: `lint`, `type-check`, `custom-script`, `smoke-test`, `ping`
+- Any pre-deploy gate failure exits with code `2` and surfaces the full error output
+- Post-deploy gate failure records a `partial` publish result instead of rolling back the adapter upload
+- `--non-interactive` suppresses retry prompts and aborts immediately on failure
+
+See `skills/publish/assets/ci-contract.md` for the full quality-gate policy.
+
+## Usage Signatures
+
+### `/publish setup`
+
+```text
+/publish setup [<target>] [--type mobile-ios|npm|droplet] [--config <path>]
+```
+
+Implementation: `bash skills/publish/scripts/setup_wizard.sh [<target>] [--type <deployment_type>] [--config <path>]`
+
+Wizard flow:
+1. Resolve or prompt for the target name.
+2. Resolve or prompt for the deployment type. Supported values: `mobile-ios`, `npm`, `droplet`.
+3. Print the secrets guide path and the opening warning from `skills/publish/assets/secrets-guide.md`.
+4. Load `skills/publish/wizards/<type>.md` and render each `## Question:` section as a prompt.
+5. Preview the generated target config as JSON.
+6. Save on confirmation by merging or creating `publish.json`.
+7. Validate the saved file with `validate_config.sh`; if validation fails, roll back the write.
+
+During setup, env-var reference answers are checked against the current shell. Missing variables only warn; they do not block save.
+
+Example invocations:
+
+```bash
+/publish setup                              # interactive, prompts for target and type
+/publish setup --type mobile-ios            # scaffold an iOS App Store target
+/publish setup --type npm                   # scaffold an npm registry target
+/publish setup npm-registry --type npm      # scaffold a target named "npm-registry"
+/publish setup --type npm-ci                   # scaffold an npm CI (Trusted Publisher) target
+/publish setup npm-ci-pkg --type npm-ci        # scaffold a target named "npm-ci-pkg"
+/publish setup --type droplet               # scaffold a Droplet SSH deploy target
+/publish setup my-droplet --type droplet    # scaffold a target named "my-droplet"
+```
+
+### `/publish deploy`
+
+```text
+/publish deploy [--target <name>] [--config <path>] [--yes] [--dry-run] [--minor | --major] [--release-notes <path>]
+```
+
+Implementation: `bash skills/publish/scripts/publish_deploy.sh [flags...]`
+
+Deploy flow:
+1. Select the target from config or `--target`
+2. Check target completeness; interactive runs auto-launch the setup wizard on missing fields
+3. Validate target environment variables
+4. Print a best-effort scrum-board summary since the last publish tag
+5. Run pre-deploy gates
+6. Generate a release-note draft and review it unless `--yes` is set
+7. Suggest and confirm the semver bump (`patch` by default in non-interactive mode unless `--minor` or `--major` is passed)
+8. Print final confirmation: `Deploy v<x.y.z> to <target>? [y/N]`
+9. Execute the adapter pipeline for the target's `type` (`ios_pipeline.sh` for `mobile-ios`, `npm_pipeline.sh` for `npm`, `npm_ci_pipeline.sh` for `npm-ci`, `droplet_pipeline.sh` for `droplet`)
+10. Run post-deploy gates and downgrade the ledger state to `partial` on failure
+11. Append the publish ledger entry, create the git tag (unless `--dry-run`), and print post-deploy manual steps
+
+Non-interactive rule: when `--yes` is used, deploy must not auto-run setup after a failure. It exits `4` and surfaces the missing fields.
+
+#### `--dry-run`
+
+`--dry-run` runs the full deploy orchestration end-to-end without producing a real release:
+
+- Every step from target selection through gates, release-note generation, and semver bump runs normally.
+- The adapter is invoked with `--dry-run` so it performs its full pipeline but skips the destructive publish step (no App Store upload for `mobile-ios`, no `npm publish` for `npm`).
+- The real git tag is **not** created.
+- A ledger entry is still appended with `platform_state: "dry-run"` so the run is auditable.
+
+Example invocations:
+
+```bash
+/publish deploy --target staging-appstore --dry-run
+/publish deploy --target npm-registry --dry-run
+/publish deploy --target npm-ci-pkg --dry-run
+```
+
+Use `--dry-run` to rehearse a release, validate that gates pass, and confirm the generated release notes without publishing.
+
+### `/publish history`
+
+```text
+/publish history [--config <path>] [--limit <count>] [--target <name>] [--json]
+```
+
+Implementation: `bash skills/publish/scripts/show_history.sh [--limit <count>] [--target <name>] [--json] [--config <path>]`
+
+### `/publish release-notes`
+
+```text
+/publish release-notes --target <name> [--config <path>] [--from-tag <tag>] [--to-ref <git-ref>] [--output <path>]
+```
+
+Implementation: `bash skills/publish/scripts/generate_release_notes.sh [--target <name>] [--from-tag <tag>] [--to-ref <git-ref>] [--output <path>] [<publish_json_path>]`
+
+Release-note rules:
+- The last publish tag is the highest semver tag on the current branch that also has a matching ledger entry in `project/logs/publish-history.json`.
+- If no prior ledger-backed tag exists, the draft includes `> First release — full history included`.
+- Scrum-board enrichment is best-effort only; missing or unreadable board data never fails the command.
+
+## Ledger & Tagging
+
+- `project/logs/publish-history.json` is append-only. New publishes add new rows; existing rows are never edited in-place.
+- `bash skills/publish/scripts/suggest_semver_bump.sh` suggests `major`, `minor`, or `patch` based on git history since the last ledger-backed publish tag.
+- `bash skills/publish/scripts/write_ledger_entry.sh <target> <adapter> <platform_state> <notes_path> [--yes] [--dry-run] [--version <vX.Y.Z>] [--config <path>]` appends the canonical publish entry and creates the matching annotated git tag.
+- `bash skills/publish/scripts/reconcile_tags.sh [--dry-run] [--config <path>]` repairs drift:
+  - git tag without ledger entry → append `partial` ledger row with note `Manually tagged without /publish`
+  - ledger entry without git tag → create the missing tag retroactively
+
+## Agent Roles
+
+See `skills/publish/assets/ownership-matrix.md` for the action-by-action ownership matrix.
+
+Summary:
+- **Developer** initiates `/publish setup`, `/publish deploy`, and release-note review
+- **Tester** may run staging deploys as part of validation and uses publish history as test context
+- **Scrum Master** never deploys directly and only reviews publish context through workflow status surfaces
+
+## Configuration Model
+
+The canonical config must validate against `skills/publish/schemas/publish.schema.json`.
+
+### Required top-level structure
+
+- `version` — schema version for the publish contract
+- `defaults` — global defaults, including the canonical publish ledger path and mandatory checks
+- `targets[]` — named deployment targets
+
+### Common target structure
+
+Every target — regardless of `type` — must define:
+- `name`
+- `type` — one of `mobile-ios`, `npm`, `droplet`
+- `checks.pre[]` / `checks.post[]`
+- `secrets` — env-var references only, never credential values
+
+Type-specific fields are documented below.
+
+## iOS App Store
+
+The `mobile-ios` adapter publishes iOS builds to App Store Connect.
+
+### Required target fields for `mobile-ios`
+
+- `type: mobile-ios`
+- `platform: ios-app-store`
+- `ios` — scheme/build/export/upload metadata used by the adapter
+
+### Required iOS env references
+
+The `mobile-ios` target must provide env-var references for:
+- `APP_STORE_CONNECT_API_KEY_ID`
+- `APP_STORE_CONNECT_ISSUER_ID`
+- `APP_STORE_CONNECT_PRIVATE_KEY_PATH`
+- `CODE_SIGN_IDENTITY`
+- `PROVISIONING_PROFILE_UUID`
+
+### iOS scope guardrails
+
+This story set intentionally does **not** implement automated App Store review submission.
+
+The iOS adapter trust boundary is explicit: publish-side external commands are limited to direct `xcodebuild` and `xcrun` invocations.
+
+## npm Registry
+
+The `npm` adapter publishes a Node package to an npm-compatible registry.
+
+- Adapter template: `skills/publish/adapters/npm.md`
+- Wizard template: `skills/publish/wizards/npm.md`
+
+See those files for the required target fields (registry URL, access, tag, `--dry-run` behaviour) and env references. Additional npm-specific schema details are owned by the npm settings block in `skills/publish/schemas/publish.schema.json`.
+
+## npm CI (OIDC Trusted Publisher)
+
+The `npm-ci` adapter publishes a Node package to npmjs.com via **GitHub Actions OIDC (Trusted Publishers)** — no `NPM_TOKEN` is stored anywhere.
+
+> Use `npm` for local publishes with a token; use `npm-ci` for CI-only publishing with OIDC (no token required).
+
+- Adapter template: `skills/publish/adapters/npm-ci.md`
+- Wizard template: `skills/publish/wizards/npm-ci.md`
+- Example config: `skills/publish/assets/publish.example.npm-ci.json`
+
+### Required target fields for `npm-ci`
+
+- `type: npm-ci`
+- `github_repo` — repository in `owner/name` format (e.g. `acme-org/my-package`)
+- `workflow_path` — path to the workflow file to generate and trigger (default: `.github/workflows/npm-publish.yml`)
+- `npm.package_name`, `npm.access`, `npm.registry`, `npm.dist_tag` — same as the `npm` adapter
+
+No `secrets` block is required. Any `secrets` block present is ignored by this adapter.
+
+### One-time prerequisite (manual)
+
+Before the first deploy, link the package to the repository on npmjs.com:
+
+1. Sign in to npmjs.com → navigate to the package page
+2. Settings → Publishing → Trusted Publishers → Add publisher
+3. Select GitHub Actions; enter `owner/repo` and the workflow file path
+4. Save
+
+Once configured, only the linked workflow can publish this package — local `npm publish` with a token will be rejected by npmjs.com for that package.
+
+### Usage examples
+
+```bash
+/publish setup --type npm-ci
+/publish deploy --target npm-ci-pkg --dry-run
+/publish deploy --target npm-ci-pkg
+```
+
+## Droplet (GitHub Actions → SSH)
+
+The `droplet` adapter deploys a project to any SSH-reachable Linux host by generating a GitHub Actions workflow that SSHes into the host on each trigger.
+
+**Trust boundary**: `publish.json` holds only *references* to GitHub Actions secret names — never the actual SSH key or host credentials. Real secrets live in GitHub Actions secrets.
+
+### Required target fields for `droplet`
+
+- `type: droplet`
+- `platform: droplet-ssh`
+- `droplet.host` — IP address or FQDN of the target host
+- `droplet.ssh_user` — SSH login username
+- `droplet.ssh_port` — SSH port (default 22)
+- `droplet.deploy_path` — absolute path to the app directory on the host
+- `droplet.github_repo` — repository in `owner/name` format
+- `droplet.deploy_branch` — branch to pull on each deploy
+- `droplet.start_cmd` — command to (re)start the service (e.g. `pm2 reload ecosystem.config.js`, `sudo systemctl restart myapp`)
+- `droplet.build_cmd` — optional build step run after `git pull`
+- `secrets.ssh_key_secret` — name of the GH Actions secret holding the SSH private key
+- `secrets.known_hosts_secret` — name of the GH Actions secret holding `ssh-keyscan` output
+
+### Required GitHub Actions secrets
+
+The generated workflow reads these from GitHub Actions secrets:
+- `DROPLET_SSH_HOST` — host IP or FQDN
+- `DROPLET_SSH_USER` — SSH username
+- `DROPLET_SSH_PORT` — SSH port
+- `DROPLET_SSH_KEY` (or value of `ssh_key_secret`) — private key contents
+- `DROPLET_KNOWN_HOSTS` (or value of `known_hosts_secret`) — `ssh-keyscan` output
+
+See `skills/publish/assets/secrets-guide.md` for setup instructions.
+
+### First-run prerequisites (manual)
+
+Before the first deploy, the target host must already have:
+- The deploy path created (`mkdir -p /var/www/myapp`)
+- An initial `git clone` of the repo at the deploy path
+- Any runtime dependencies installed (Node, PM2, etc.)
+
+The adapter does not bootstrap the host — it only drives the continuous-deploy loop.
+
+### Usage examples
+
+```bash
+/publish setup --type droplet
+/publish deploy --target my-droplet --dry-run
+/publish deploy --target my-droplet
+```

package/skills/publish/adapters/droplet.md

@@ -0,0 +1,200 @@
+# `droplet` Adapter
+
+The `droplet` adapter drives the `/publish deploy` flow for SSH-reachable Linux
+host targets. Despite the name, nothing in the flow is DigitalOcean-specific — it
+works against any Linux host reachable via SSH. The adapter generates a GitHub
+Actions workflow that performs all deploy orchestration remotely; the local machine
+never SSHes directly into the host.
+
+## Purpose
+
+Deploy a web application or service from a GitHub repository to a Linux host
+(DigitalOcean Droplet, VPS, bare-metal server, or any SSH-reachable machine) by:
+
+1. Generating a GitHub Actions workflow that SSHes into the host using
+   `appleboy/ssh-action`.
+2. Committing the workflow file (`.github/workflows/publish-droplet.yml`) to the
+   repository.
+3. Triggering the workflow via `gh workflow run`.
+
+The host stays passive — it does not poll; all orchestration originates from
+GitHub Actions. The user supplies `build_cmd` and `start_cmd`; the adapter makes
+no assumptions about the runtime stack (no PM2 templates, no nginx config, no
+systemd unit generation in v1).
+
+## Trust Boundary
+
+`publish.json` holds **only** configuration values and secret name references —
+never actual secrets. The five secret values (SSH private key, host, user, port,
+known_hosts) live exclusively in GitHub Actions secrets.
+
+```
+publish.json                GitHub Actions secrets
+──────────────              ──────────────────────────────
+ssh_key_secret: "DROPLET_SSH_KEY"   →  ${{ secrets.DROPLET_SSH_KEY }}   ← private key
+known_hosts_secret: "DROPLET_KNOWN_HOSTS" → ${{ secrets.DROPLET_KNOWN_HOSTS }}
+host: "192.168.1.10"  (baked into workflow — not a secret)
+```
+
+`host`, `ssh_user`, `ssh_port`, `deploy_path`, `deploy_branch`, `build_cmd`, and
+`start_cmd` are non-sensitive configuration values stored in `publish.json` and
+expanded into the generated workflow YAML. If you prefer to keep the host address
+private too, supply it via a GitHub Actions secret and reference it in `start_cmd`.
+
+## Invocation Contract
+
+### Inputs from `publish.json`
+
+A `droplet` target must define:
+
+- `name`
+- `type: droplet`
+- `platform: droplet-ssh`
+- `checks.pre[]` / `checks.post[]`
+- `secrets.ssh_key_secret` — GitHub Actions secret name for the SSH private key
+- `secrets.known_hosts_secret` — GitHub Actions secret name for known_hosts
+- `droplet.host` — IP or FQDN of the target host
+- `droplet.ssh_user` — SSH username
+- `droplet.ssh_port` — SSH port (default: 22)
+- `droplet.deploy_path` — absolute path on the remote host
+- `droplet.github_repo` — `owner/name` format
+- `droplet.deploy_branch` — branch to pull during deploy
+- `droplet.start_cmd` — required; command to (re)start the service
+- `droplet.build_cmd` — optional; build command to run before starting
+
+### Required environment and tools
+
+The adapter requires the following tools at invocation time:
+
+- `jq` — to read `publish.json` target config
+- `git` — to commit the generated workflow file
+- `gh` — GitHub CLI, to trigger the workflow via `gh workflow run`
+
+The `gh` CLI must be authenticated (`gh auth login`) before running
+`/publish deploy` against a droplet target.
+
+### Pipeline entrypoint
+
+```bash
+bash skills/publish/scripts/droplet_pipeline.sh \
+  --target <name> \
+  --config <path-to-publish.json> \
+  [--dry-run]
+```
+
+## Execution Phases
+
+Run the adapter phases in this exact order:
+
+1. **`validate`** — call `validate_droplet_env.sh`; abort with exit 4 if any
+   required field in the target config is missing or empty.
+
+2. **`generate-workflow`** — produce the GitHub Actions YAML in memory using a
+   here-doc. The `appleboy/ssh-action` step is pinned to a specific commit SHA
+   (not a floating tag) to prevent supply-chain surprises. In `--dry-run` mode,
+   print the YAML to stdout and exit 0 without writing any file.
+
+3. **`commit-workflow`** — write the YAML to
+   `.github/workflows/publish-droplet.yml` (creating the directory if needed)
+   and commit it with:
+   ```
+   git add .github/workflows/publish-droplet.yml
+   git commit -m "chore(publish): update droplet workflow for target <name>"
+   ```
+   If the file already exists and the content is unchanged (`git diff --quiet`),
+   skip the commit — the operation is idempotent.
+
+4. **`trigger`** — invoke `gh workflow run publish-droplet.yml --repo <github_repo>`
+   to start the workflow. After dispatching, retrieve the run URL via
+   `gh run list --workflow publish-droplet.yml --limit 1 --json url`.
+
+5. **`triggered`** — print the workflow run URL to stdout. The caller
+   (`publish_deploy.sh`) writes the ledger entry with `platform_state: "triggered"`.
+
+## Dry-run Mode
+
+`--dry-run` is supported for safe end-to-end rehearsals without triggering a
+real deploy.
+
+Behavior in dry-run mode:
+
+- The `validate` phase runs normally; config errors still surface.
+- The `generate-workflow` phase runs normally; the YAML is printed to stdout.
+- The `commit-workflow` phase is **skipped** — no file is written, no git commit
+  is made.
+- The `trigger` phase is **skipped** — `gh workflow run` is not called.
+- The adapter exits 0 after printing the YAML.
+- The ledger entry written by `publish_deploy.sh` will have
+  `platform_state: "dry-run"`.
+
+## Exit Codes
+
+| Code | Meaning                                                           |
+|------|-------------------------------------------------------------------|
+| `0`  | Pipeline completed successfully, or `--dry-run` finished cleanly  |
+| `4`  | Config or env invalid — required field missing or `jq`/`gh` absent|
+| `3`  | Workflow trigger failure (`gh workflow run` exited non-zero)       |
+
+## Output Artefacts
+
+A successful non-dry-run produces:
+
+- `.github/workflows/publish-droplet.yml` committed to the repository
+- A `gh workflow run` dispatch recorded in GitHub Actions history
+- A workflow run URL printed to stdout
+- A history entry in `project/logs/publish-history.json` written by
+  `publish_deploy.sh` with `platform_state: "triggered"`
+
+## Post-deploy manual steps
+
+After a successful deploy trigger, the deploy flow must print:
+
+Deploy triggered. Next manual steps:
+1. Monitor the workflow run at the URL printed above.
+2. If the run fails, check the GitHub Actions logs for SSH or script errors.
+3. Push a commit to `<deploy_branch>` to auto-trigger future deploys once the
+   generated workflow has been merged into the branch.
+
+Print the same block regardless of interactive/non-interactive mode so CI logs
+capture it.
+
+## First-run bootstrap caveat
+
+Creating the deploy path and performing the initial `git clone` on the remote
+host is **out of scope for v1** and must be done manually before the first
+`/publish deploy` invocation.
+
+Minimum bootstrap on the host:
+
+```bash
+# SSH into the host
+ssh <ssh_user>@<host>
+
+# Clone the repository into deploy_path
+git clone https://github.com/<github_repo>.git <deploy_path>
+cd <deploy_path>
+
+# Install runtime dependencies (example for Node.js)
+npm install
+
+# Verify start_cmd works
+# e.g.: pm2 reload ecosystem.config.js
+```
+
+Document these steps for your team. The wizard emits a post-setup instructions
+file at `project/instructions/E22_S07_INSTRUCTIONS.md` with a bootstrap checklist.
+
+## Runtime agnosticism
+
+The adapter does not generate PM2 configs, nginx virtual-host files, or systemd
+unit files. Users embed runtime-specific commands directly in `build_cmd` and
+`start_cmd`. Examples:
+
+| Runtime   | start_cmd example                                   |
+|-----------|-----------------------------------------------------|
+| PM2       | `pm2 reload ecosystem.config.js`                    |
+| systemd   | `sudo systemctl restart myapp`                      |
+| Docker    | `docker compose up -d --build`                      |
+| Custom    | `./scripts/restart.sh`                              |
+
+Opinionated runtime templates are deferred to future adapter versions.

package/skills/publish/adapters/mobile-ios.md

@@ -0,0 +1,114 @@
+# `mobile-ios` Adapter
+
+The `mobile-ios` adapter drives the `/publish deploy` flow for iOS App Store targets.
+It is a prompt/template contract for the agent layer and delegates concrete execution to
+`skills/publish/scripts/ios_pipeline.sh`.
+
+## Invocation Contract
+
+### Inputs from `publish.json`
+
+A `mobile-ios` target must define:
+
+- `name`
+- `type: mobile-ios`
+- `platform: ios-app-store`
+- `checks.pre[]` / `checks.post[]`
+- `secrets.app_store_connect_api_key_id`
+- `secrets.app_store_connect_issuer_id`
+- `secrets.app_store_connect_private_key_path`
+- `secrets.code_sign_identity`
+- `secrets.provisioning_profile_uuid`
+- `ios.scheme`
+- `ios.configuration`
+- `ios.archive_path`
+- `ios.export_path`
+- `ios.export_method` (`ad-hoc` or `app-store`)
+- `ios.bundle_id`
+- `ios.team_id`
+- `ios.app_store_app_id`
+- exactly one of `ios.project_path` or `ios.workspace_path`
+
+### Required environment variables
+
+The adapter uses env-var references only and never stores secret values in repo files.
+The required env vars are:
+
+- `APP_STORE_CONNECT_API_KEY_ID`
+- `APP_STORE_CONNECT_ISSUER_ID`
+- `APP_STORE_CONNECT_PRIVATE_KEY_PATH`
+- `CODE_SIGN_IDENTITY`
+- `PROVISIONING_PROFILE_UUID`
+
+Validate them before execution with:
+
+```bash
+bash skills/publish/scripts/validate_ios_env.sh <path-to-publish.json>
+```
+
+### Pipeline entrypoint
+
+```bash
+bash skills/publish/scripts/ios_pipeline.sh <target> <path-to-publish.json> [--dry-run] [--non-interactive]
+```
+
+## Execution Phases
+
+Run the adapter phases in this exact order:
+
+1. `validate`
+2. `build`
+3. `sign`
+4. `export`
+5. `upload`
+
+Quality gates run outside this adapter. Once control enters the adapter, external publish-side commands are restricted to direct `xcodebuild` and `xcrun` invocations.
+
+## State Machine
+
+The adapter records these transitions in `project/logs/publish-history.json`:
+
+```text
+idle → building → signing → exporting → uploading → uploaded
+                                  └──────────────────────→ failed
+```
+
+### State meanings
+
+- `idle` — conceptual pre-start state before a history row is appended
+- `building` — archive command is about to run or is running
+- `signing` — export options are being generated using env refs and config
+- `exporting` — `xcodebuild -exportArchive` is running
+- `uploading` — the IPA is being uploaded with `xcrun`
+- `uploaded` — upload finished successfully
+- `failed` — any build/export/upload failure; `completed_at` must be set
+
+## Dry-run Mode
+
+`--dry-run` is mandatory for safe CI validation without live Apple credentials.
+
+Behavior:
+
+- All `xcodebuild` / `xcrun` commands are printed with a `[DRY RUN]` prefix.
+- Commands are **not** executed.
+- State-machine writes still happen so reviewers can inspect the planned flow.
+- The adapter exits `0` after simulating a successful upload.
+
+## Exit Codes
+
+| Code | Meaning |
+|---|---|
+| `0` | Pipeline completed successfully or dry-run finished successfully |
+| `3` | Build, sign, export, upload, or history-update failure |
+| `4` | Config or env validation failure |
+
+## Post-deploy manual steps
+
+After a successful upload, the deploy flow must print:
+
+✅ Upload complete. Next manual steps:
+1. Go to App Store Connect → Apps → [Your App] → TestFlight (or App Store)
+2. Find the new build and submit for review / release
+3. Set release notes if required
+
+Print the same block in `--non-interactive` mode so CI logs capture it.