Skip to content

Update Hummingbird hb CLI guidance#99

Merged
gaelic-ghost merged 2 commits into
mainfrom
skills/hummingbird-cli-sync
Jul 2, 2026
Merged

Update Hummingbird hb CLI guidance#99
gaelic-ghost merged 2 commits into
mainfrom
skills/hummingbird-cli-sync

Conversation

@gaelic-ghost

@gaelic-ghost gaelic-ghost commented Jul 2, 2026

Copy link
Copy Markdown
Owner

Summary

  • update Hummingbird bootstrap guidance for current hb Server/Lambda prompts, generated swift-configuration, and template package shape
  • clarify Lambda + OpenAPI guidance around OpenAPIHummingbird, hummingbird-lambda, and separate swift-openapi-lambda transport
  • add sync-hummingbird-service-guidance for existing Hummingbird repos and bump Socket to 7.8.0

Closes #98

Verification

  • uv run scripts/validate_socket_metadata.py
  • jq empty docs/architecture/architecture.json
  • git diff --check

Summary by CodeRabbit

  • New Features

    • Added new guidance for syncing existing Hummingbird service setups and refreshed server-side Swift workflow instructions.
    • Expanded server-side Swift guidance to better cover Server vs. Lambda app shapes, configuration handling, and OpenAPI/Hummingbird workflows.
  • Documentation

    • Updated roadmap and architecture docs to reflect the new guidance and skill inventory.
  • Chores

    • Bumped project and plugin versions from 7.7.0 to 7.8.0 across multiple packages and manifests.

@gaelic-ghost gaelic-ghost added the documentation Improvements or additions to documentation label Jul 2, 2026
@coderabbitai

coderabbitai Bot commented Jul 2, 2026

Copy link
Copy Markdown

Review Change Stack

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 5b764a92-c0ce-4b59-b8b5-c4e022fdf5c4

📥 Commits

Reviewing files that changed from the base of the PR and between a2cd47e and 30bc4db.

⛔ Files ignored due to path filters (8)
  • plugins/agent-portability-skills/uv.lock is excluded by !**/*.lock
  • plugins/apple-dev-skills/uv.lock is excluded by !**/*.lock
  • plugins/cardhop-app/mcp/uv.lock is excluded by !**/*.lock
  • plugins/productivity-skills/uv.lock is excluded by !**/*.lock
  • plugins/python-skills/uv.lock is excluded by !**/*.lock
  • plugins/things-app/mcp/uv.lock is excluded by !**/*.lock
  • plugins/things-app/uv.lock is excluded by !**/*.lock
  • uv.lock is excluded by !**/*.lock
📒 Files selected for processing (39)
  • README.md
  • ROADMAP.md
  • docs/architecture/ARCHITECTURE.md
  • docs/architecture/architecture.json
  • plugins/agent-portability-skills/.codex-plugin/plugin.json
  • plugins/agent-portability-skills/pyproject.toml
  • plugins/android-dev-skills/.codex-plugin/plugin.json
  • plugins/apple-dev-skills/.codex-plugin/plugin.json
  • plugins/apple-dev-skills/pyproject.toml
  • plugins/cardhop-app/.codex-plugin/plugin.json
  • plugins/cardhop-app/mcp/pyproject.toml
  • plugins/codex-utilities/.codex-plugin/plugin.json
  • plugins/dotnet-skills/.codex-plugin/plugin.json
  • plugins/productivity-skills/.codex-plugin/plugin.json
  • plugins/productivity-skills/pyproject.toml
  • plugins/python-skills/.codex-plugin/plugin.json
  • plugins/python-skills/pyproject.toml
  • plugins/reverse-engineering-skills/.codex-plugin/plugin.json
  • plugins/rust-skills/.codex-plugin/plugin.json
  • plugins/server-side-jvm/.codex-plugin/plugin.json
  • plugins/server-side-swift/.codex-plugin/plugin.json
  • plugins/server-side-swift/AGENTS.md
  • plugins/server-side-swift/skills/auth-authorization-workflow/SKILL.md
  • plugins/server-side-swift/skills/bootstrap-hummingbird-service/SKILL.md
  • plugins/server-side-swift/skills/bootstrap-hummingbird-service/assets/AGENTS.md
  • plugins/server-side-swift/skills/fly-io-deployment-workflow/SKILL.md
  • plugins/server-side-swift/skills/hummingbird-server-workflow/SKILL.md
  • plugins/server-side-swift/skills/openapi-rpc-workflow/SKILL.md
  • plugins/server-side-swift/skills/sync-hummingbird-service-guidance/SKILL.md
  • plugins/server-side-swift/skills/sync-hummingbird-service-guidance/assets/AGENTS.md
  • plugins/server-side-swift/skills/sync-hummingbird-service-guidance/assets/append-section.md
  • plugins/spotify/.codex-plugin/plugin.json
  • plugins/swift-lang/.codex-plugin/plugin.json
  • plugins/swiftasb-skills/.codex-plugin/plugin.json
  • plugins/things-app/.codex-plugin/plugin.json
  • plugins/things-app/mcp/pyproject.toml
  • plugins/things-app/pyproject.toml
  • plugins/web-dev-skills/.codex-plugin/plugin.json
  • pyproject.toml

📝 Walkthrough

Walkthrough

This PR updates server-side Swift/Hummingbird guidance to reflect the current hb CLI Server/Lambda selection flow, swift-configuration support, and Lambda+OpenAPI transport distinctions (hummingbird-lambda/OpenAPIHummingbird vs swift-openapi-lambda). It adds a new sync-hummingbird-service-guidance skill with assets, registers it in architecture docs, updates README/ROADMAP, and bumps package/plugin versions from 7.7.0 to 7.8.0 across the monorepo.

Changes

Hummingbird guidance and sync skill

Layer / File(s) Summary
Bootstrap skill and shared defaults
plugins/server-side-swift/AGENTS.md, plugins/server-side-swift/skills/bootstrap-hummingbird-service/SKILL.md, plugins/server-side-swift/skills/bootstrap-hummingbird-service/assets/AGENTS.md
Bootstrap workflow guidance is rewritten to preserve hb-selected Server/Lambda shape, use generated swift-configuration, default long-running servers to Fluent+PostgreSQL+Compose, and add explicit guardrails against hand-rolled scaffolding.
Downstream workflow guidance
plugins/server-side-swift/skills/hummingbird-server-workflow/SKILL.md, .../openapi-rpc-workflow/SKILL.md, .../auth-authorization-workflow/SKILL.md, .../fly-io-deployment-workflow/SKILL.md
Workflow skills add Server/Lambda shape and swift-configuration preservation notes, clarify hummingbird-lambda/OpenAPIHummingbird vs swift-openapi-lambda transport roles, add an auth-boundary caution for Lambda/API Gateway deployments, and a Fly.io guardrail against forcing Lambda apps into long-running deployment.
New sync-hummingbird-service-guidance skill
plugins/server-side-swift/skills/sync-hummingbird-service-guidance/SKILL.md, .../assets/AGENTS.md, .../assets/append-section.md
New skill defines detection, sync workflow for repo-local AGENTS.md/Codex environment files, inputs/outputs, guardrails, and handoff guidance, with accompanying asset templates.
Plugin metadata, docs, and architecture registration
plugins/server-side-swift/.codex-plugin/plugin.json, README.md, ROADMAP.md, docs/architecture/ARCHITECTURE.md, docs/architecture/architecture.json
Plugin manifest version/description/keywords/prompts updated for the new capabilities; README/ROADMAP mention guidance sync; architecture docs and JSON register the new skill as evidence, relationship, and target.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Plugin and package version bumps

Layer / File(s) Summary
Version bump to 7.8.0
plugins/*/.codex-plugin/plugin.json, plugins/*/pyproject.toml, pyproject.toml
Version fields bumped uniformly from 7.7.0 to 7.8.0 across numerous plugin manifests and pyproject files.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Developer
  participant SyncSkill as sync-hummingbird-service-guidance
  participant Repo
  participant AgentsMd as AGENTS.md
  participant CodexEnv as .codex/environments/hummingbird.toml

  Developer->>SyncSkill: invoke sync-hummingbird-service-guidance
  SyncSkill->>Repo: detect Package.swift and Hummingbird usage
  Repo-->>SyncSkill: repo classification (path_type)
  SyncSkill->>AgentsMd: align repo-local guidance
  SyncSkill->>CodexEnv: sync local environment config
  SyncSkill-->>Developer: status and output summary
Loading

Possibly related PRs

  • gaelic-ghost/socket#54: Extends the same plugins/server-side-swift plugin surface with AGENTS.md/plugin metadata updates and adds the new sync skill.
  • gaelic-ghost/socket#63: Both PRs modify plugins/server-side-swift/skills/hummingbird-server-workflow/SKILL.md guidance.
  • gaelic-ghost/socket#85: Both PRs modify the same Hummingbird guidance files, including AGENTS.md, plugin.json, and hummingbird-server-workflow/SKILL.md.

Suggested labels: enhancement

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch skills/hummingbird-cli-sync

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@gaelic-ghost gaelic-ghost merged commit 6036bdb into main Jul 2, 2026
1 of 2 checks passed
@gaelic-ghost gaelic-ghost deleted the skills/hummingbird-cli-sync branch July 2, 2026 14:59

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 30bc4db0ff

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment on lines +79 to +81
- if `AGENTS.md` is missing, copy `assets/AGENTS.md`
- if `AGENTS.md` exists and already contains the managed Hummingbird sync section, keep the file unchanged except for deliberate user-requested edits
- if `AGENTS.md` exists but lacks the managed section, append `assets/append-section.md` as a bounded section

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Keep copied Hummingbird guidance detectable

When the target repo has no AGENTS.md, this path copies assets/AGENTS.md, but that asset does not include the BEGIN SOCKET HUMMINGBIRD GUIDANCE/END markers that the next branch uses to detect an already-synced file. A subsequent run against that same repo will therefore fall through to the append path and duplicate the Hummingbird guidance instead of being idempotent or refreshable; either the full copied asset needs the managed marker, or the detection/replacement logic needs to recognize the copied baseline.

Useful? React with 👍 / 👎.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Clarify hb Lambda + OpenAPI guidance

1 participant