Add OpenAI provider integration

.github/workflows/ci.yml

@@ -4,7 +4,6 @@ on:
   push:
     branches: [main]
   pull_request:
-    branches: [main]
   workflow_dispatch:
 
 permissions:
@@ -50,19 +49,120 @@ jobs:
       - name: Install the catalog plugin from this checkout
         run: fledge plugins install . --yes --non-interactive
 
-      - name: Dogfood a repository-local skill install
+      - name: Dogfood the complete catalog lifecycle
+        shell: bash
+        run: |
+          test_root="$(mktemp -d)"
+          trap 'rm -rf "$test_root"' EXIT
+          fledge skills list --json > "$test_root/catalog.json"
+
+          python3 - "$test_root/catalog.json" <<'PY'
+          import json
+          import sys
+
+          with open(sys.argv[1], encoding="utf-8") as source:
+              catalog = json.load(source)
+          assert len(catalog["skills"]) == 15
+          assert catalog["skills"] == sorted(catalog["skills"])
+          PY
+
+          for host in codex claude cursor gemini grok openai; do
+            test_repo="$test_root/$host"
+            mkdir -p "$test_repo"
+            git -C "$test_repo" init -q
+
+            while IFS= read -r skill; do
+              fledge skills install "$skill" --repo "$test_repo" --host "$host"
+            done < <(fledge skills list)
+
+            fledge skills status --repo "$test_repo" --json > "$test_root/$host-status.json"
+            python3 - "$test_root/$host-status.json" "$host" <<'PY'
+          import json
+          import sys
+
+          with open(sys.argv[1], encoding="utf-8") as source:
+              status = json.load(source)
+          assert len(status["installs"]) == 15
+          assert {item["host"] for item in status["installs"]} == {sys.argv[2]}
+          assert {item["state"] for item in status["installs"]} == {"current"}
+          PY
+
+            fledge skills update --all --repo "$test_repo" --host "$host" --dry-run
+            fledge skills uninstall agent-coordination --repo "$test_repo" --host "$host" --dry-run
+            fledge skills uninstall agent-coordination --repo "$test_repo" --host "$host"
+            test ! -e "$test_repo/.$host/skills/agent-coordination"
+          done
+
+      - name: Prove Grok placement with Let find skills
         shell: bash
         run: |
-          test_repo="$(mktemp -d)"
-          trap 'rm -rf "$test_repo"' EXIT
+          # Let’s fledge plugin build hook requires Bun.
+          curl -fsSL https://bun.sh/install | bash
+          export BUN_INSTALL="${HOME}/.bun"
+          export PATH="${BUN_INSTALL}/bin:${PATH}"
+          command -v bun
+          bun --version
+          fledge plugins install CorvidLabs/let@v0.2.0 --yes --non-interactive
+          test_repo="$(mktemp -d)/grok-let"
+          mkdir -p "$test_repo"
           git -C "$test_repo" init -q
+          fledge skills install agent-coordination --repo "$test_repo" --host grok
+          fledge skills install fledge-workflows --repo "$test_repo" --host grok
+          fledge let find skills --scope project --host grok \
+            --repo "$test_repo" --cwd "$test_repo" --json \
+            > /tmp/let-find-skills-grok.json
+          python3 - "$test_repo" <<'PY'
+          import json
+          import sys
+          from pathlib import Path
 
-          fledge skills list | grep -qx 'agent-coordination'
-          fledge skills list | grep -qx 'spec-sync'
-          fledge skills install agent-coordination --repo "$test_repo" --host codex
-          fledge skills install spec-sync --repo "$test_repo" --host codex
-          fledge skills status --repo "$test_repo" | grep -q '^agent-coordination'
-          fledge skills status --repo "$test_repo" | grep -q '^spec-sync'
+          repo = Path(sys.argv[1]).resolve()
+          payload = json.loads(Path("/tmp/let-find-skills-grok.json").read_text(encoding="utf-8"))
+          assert payload.get("ok") is True, payload
+          project = []
+          for item in payload.get("data", {}).get("items", []):
+              if item.get("scope") != "project" or item.get("host") != "grok":
+                  continue
+              path = Path(item.get("path", "")).resolve()
+              try:
+                  path.relative_to(repo)
+              except ValueError:
+                  continue
+              project.append(item)
+          names = {item["name"] for item in project}
+          assert names >= {"agent-coordination", "fledge-workflows"}, names
+          for item in project:
+              expected = repo / ".grok" / "skills" / item["name"] / "SKILL.md"
+              assert Path(item["path"]).resolve() == expected.resolve()
+          print("let find skills proof ok:", sorted(names))
+          PY
+          fledge skills uninstall agent-coordination --repo "$test_repo" --host grok
+          test ! -e "$test_repo/.grok/skills/agent-coordination"
+          fledge let find skills --scope project --host grok \
+            --repo "$test_repo" --cwd "$test_repo" \
+            --query agent-coordination --json \
+            > /tmp/let-find-after-uninstall.json
+          python3 - "$test_repo" <<'PY'
+          import json
+          import sys
+          from pathlib import Path
 
-          test -f "$test_repo/.codex/skills/agent-coordination/SKILL.md"
-          test -f "$test_repo/.codex/skills/spec-sync/SKILL.md"
+          repo = Path(sys.argv[1]).resolve()
+          payload = json.loads(Path("/tmp/let-find-after-uninstall.json").read_text(encoding="utf-8"))
+          assert payload.get("ok") is True, payload
+          project = []
+          for item in payload.get("data", {}).get("items", []):
+              if (
+                  item.get("scope") != "project"
+                  or item.get("host") != "grok"
+                  or item.get("name") != "agent-coordination"
+              ):
+                  continue
+              try:
+                  Path(item.get("path", "")).resolve().relative_to(repo)
+              except ValueError:
+                  continue
+              project.append(item)
+          assert not project, project
+          print("let post-uninstall proof ok")
+          PY

README.md

@@ -1,67 +1,130 @@
 # CorvidLabs Skills
 
-Versioned, shared skills for CorvidLabs agents. This repository holds cross-project
-operating knowledge; each product repository keeps its own architecture and generated
-Spec Sync material.
-
-## Initial skills
-
-- `agent-coordination` — use `fledge let` to discover the correct context, then use
-  `fledge rune` only to observe or send a scoped message to that confirmed agent session.
-- `let` — locate the authoritative repository context, worktrees, sessions, instructions,
-  skills, and recent activity before acting.
-- `rune` — safely observe or drive a confirmed CLI-agent session through a bounded PTY.
-- `augur` — inspect deterministic Git change risk and enforce explicit review or block gates.
-- `attest` — verify or record provenance evidence for exact reviewed commits.
-- `atlas` — map specifications to code ownership, drift, review queues, and coverage gaps.
-- `three-md` — author and validate general layered `.3md` documents.
-- `agent-3md` — validate, route, preview, and explicitly execute `agent.3md` tool templates.
-- `spec-sync` — the shared baseline for bidirectional Spec Sync work. A project may
-  generate a richer local version from its own configuration.
-- `corvid-swift-package` — the shared operating baseline for CorvidLabs Swift packages:
-  Fledge-first discovery, Swift 6 concurrency, cross-platform support, and release hygiene.
-- `corvid-web-bun` — build and validate CorvidLabs Bun web projects while deferring
-  framework, architecture, and release policy to the repository-local guides.
-- `fledge-workflows` — discover and use repository-defined Fledge tasks and lanes.
-- `spec-sync-routing` — route shared guidance to the repo-generated Spec Sync truth.
-- `ci-release-hygiene` — keep CI and release evidence tied to the current commit.
-- `public-release-audit` — audit a private repository before an explicit public-release decision.
-
-## Install with Fledge
-
-Bootstrap the Skills plugin once:
+Public, versioned operating knowledge for software agents working with CorvidLabs tools.
+Each skill is a portable `SKILL.md`; Fledge provides safe repository-local installation,
+status, update, and uninstall commands.
+
+Product repositories remain authoritative for their own architecture, commands, and
+generated Spec Sync material.
+
+## Quick start
+
+Install the catalog plugin, inspect it, and add only the skills a repository needs:
 
 ```sh
 fledge plugins install CorvidLabs/skills
+fledge skills list
+fledge skills install agent-coordination --host codex
+fledge skills status
 ```
 
-Pin the source to a released tag when a catalog release is available.
+To pin a published catalog release, add its tag to the source, for example:
 
-Then install a selected skill into the current Git repository:
+```sh
+fledge plugins install CorvidLabs/skills@v0.2.0
+```
+
+## Catalog
+
+### Coordination and discovery
+
+| Skill | Purpose |
+| --- | --- |
+| `agent-coordination` | Coordinate scoped discovery, Rune, Fledge, and Spec Sync verification. |
+| `let` | Discover local agent context when its federated metadata scope is explicitly permitted. |
+| `rune` | Observe or control a confirmed CLI-agent session through a bounded PTY. |
+| `fledge-workflows` | Discover and use repository-defined Fledge tasks, lanes, plugins, and work commands. |
+
+### Product tools
+
+| Skill | Purpose |
+| --- | --- |
+| `augur` | Inspect deterministic Git change risk and apply explicit review or block gates. |
+| `attest` | Verify or record provenance evidence for exact reviewed commits. |
+| `atlas` | Map specifications to ownership, drift, review queues, and coverage gaps. |
+| `three-md` | Author and validate layered `.3md` documents. |
+| `agent-3md` | Validate, route, preview, and explicitly execute `agent.3md` tool templates. |
+
+### Project engineering
+
+| Skill | Purpose |
+| --- | --- |
+| `spec-sync` | Apply the shared, version-neutral baseline for bidirectional Spec Sync work. |
+| `spec-sync-routing` | Route shared guidance to authoritative repository-generated Spec Sync instructions. |
+| `corvid-swift-package` | Build CorvidLabs Swift packages with Fledge-first, Swift 6, and cross-platform practices. |
+| `corvid-web-bun` | Build and verify local Bun/TypeScript web tools. |
+| `ci-release-hygiene` | Tie CI and release evidence to the exact current commit. |
+| `public-release-audit` | Audit a repository before an explicit public-release decision. |
+
+## Agent compatibility
+
+The skill content is agent-neutral Markdown. Any agent that can load a `SKILL.md` from
+repository context can use it. Fledge currently provides automatic, collision-safe placement
+for these hosts:
+
+| Host | Repository-local destination | Automatic placement |
+| --- | --- | --- |
+| Codex | `.codex/skills/<skill>` | Yes |
+| Claude | `.claude/skills/<skill>` | Yes |
+| Cursor | `.cursor/skills/<skill>` | Yes |
+| Gemini | `.gemini/skills/<skill>` | Yes |
+| Grok | `.grok/skills/<skill>` | Yes |
+| OpenAI | `.openai/skills/<skill>` | Yes |
+| Other agents | Agent-defined | No; use the agent's documented skill path. |
+
+Host placement does not translate private context or product-specific assumptions into a skill.
+All catalog content and examples must remain usable from public CorvidLabs sources.
+Fledge lifecycle tracking applies to the six automatic placements; a custom agent path remains
+managed by that agent or by the user.
+
+## Manage installed skills
+
+Installs copy by default. Use `--link` only while developing this catalog locally.
+Every placement is recorded in `.corvid-skills.json` with its source revision, mode,
+destination, and content digest.
 
 ```sh
-fledge skills list
-fledge skills install agent-coordination --host codex
+# Inspect human-readable or machine-readable state.
+fledge skills status
+fledge skills status --json
+
+# Preview, then update one skill or every managed skill.
+fledge skills update augur --dry-run
+fledge skills update --all --dry-run
+fledge skills update --all
+
+# Preview, then remove one manifest-owned skill.
+fledge skills uninstall augur --dry-run
+fledge skills uninstall augur
+```
+
+`status` reports `current`, `modified`, or `missing`. Update and uninstall refuse modified
+or missing copies, so local work is never overwritten or removed. For a manifest-owned link,
+Fledge verifies the exact link target before refreshing metadata or removing the link.
+
+Update the catalog plugin separately when you want newer source content:
+
+```sh
+fledge plugins update fledge-plugin-skills
 fledge skills status
+fledge skills update --all --dry-run
+fledge skills update --all
 ```
 
-`--host auto` is supported only when exactly one of the supported repository-local
-host directories already exists. Use `--host` when setting up a new project or
-when more than one host is present. Installs copy by default; `--link` is for
-local skill development only.
+Use `--host codex`, `--host claude`, `--host cursor`, `--host gemini`, `--host grok`, or
+`--host openai` to select one placement when a skill is installed for multiple hosts. `--host auto`
+is available for install only when exactly one supported host directory already exists.
 
-`status` reports each managed install as `current`, `modified`, or `missing` by comparing
-the recorded digest with safe repository-local placement. A generated Spec Sync skill owns
-`.codex/skills/spec-sync`; do not install the shared skill over it. Install
-`spec-sync-routing` beside generated guidance when shared routing is useful.
+## Spec Sync placement
 
-The initial plugin deliberately supports `list`, `install`, and `status` only.
-Safe managed `update` and `uninstall` will follow after their ownership and
-local-modification rules are tested.
+A project-generated Spec Sync skill owns its repository-local `spec-sync` destination.
+The installer never overwrites an existing directory. Keep generated guidance in place and
+install `spec-sync-routing` beside it when shared routing is useful. This policy does not
+depend on a particular Spec Sync generator version or generated directory layout.
 
 ## Verify the catalog
 
-Use the repository-defined Fledge lanes:
+Run the same Fledge-native checks used by CI:
 
 ```sh
 fledge run --list
@@ -70,30 +133,23 @@ fledge lanes run verify
 fledge lanes run audit
 ```
 
-The verification lane requires Bash, Python 3, and ShellCheck. The audit lane also
-requires Gitleaks and redacts any finding output.
-
-## Direct installer
+The verification lane requires Bash, Python 3, and ShellCheck. The audit lane also requires
+Gitleaks and redacts any finding output.
 
-Install a named skill into a repository-local agent directory:
+The direct installer is available for debugging or environments without plugin dispatch:
 
 ```sh
+bin/corvid-skills list --json
 bin/corvid-skills install agent-coordination --repo /path/to/project --host codex
-bin/corvid-skills install spec-sync --repo /path/to/project --host claude
-```
-
-Supported hosts are `codex`, `claude`, and `cursor`. Installations copy the selected
-skill and record its source revision, destination, install mode, and content digest
-in `.corvid-skills.json`. Existing skill directories are never overwritten.
-
-```sh
-bin/corvid-skills list
-bin/corvid-skills install agent-coordination --repo . --host codex --link
+bin/corvid-skills status --repo /path/to/project --json
+bin/corvid-skills update agent-coordination --repo /path/to/project --dry-run
+bin/corvid-skills uninstall agent-coordination --repo /path/to/project --dry-run
 ```
 
 ## Design rules
 
-- Shared skills teach reusable operating practices.
-- Repo-local skills are authoritative for that repo's commands, architecture, and policy.
-- A generated Spec Sync skill is authoritative and must not be overwritten by the shared baseline.
-- Installer changes are explicit and repository-local by default.
+- Keep one concise skill per tool or workflow; avoid aliases and overlapping boilerplate.
+- Verify real public commands before documenting them.
+- Treat repository-local instructions as authoritative for that repository.
+- Never include private paths, session content, secrets, user metadata, or private-repository assumptions.
+- Make installation and lifecycle mutations explicit, manifest-owned, and repository-local.