diff --git a/README.md b/README.md index 0248eda..c4a9bc7 100644 --- a/README.md +++ b/README.md @@ -1,23 +1,44 @@ # CorvidLabs Skills 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. +Each skill is a portable `SKILL.md`; Fledge provides safe installation (repository-local +or machine-global), 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: +Install the catalog plugin, then add skills **one at a time** (there is no `install --all`). + +**Minimal core — repository-local** (good default for a single project): ```sh fledge plugins install CorvidLabs/skills fledge skills list fledge skills install agent-coordination --host codex +fledge skills install fledge-workflows --host codex fledge skills status ``` +**Minimal core — machine-global** (available to every project for that host agent): + +```sh +fledge plugins install CorvidLabs/skills +fledge skills install agent-coordination --global --host claude +fledge skills install fledge-workflows --global --host claude +fledge skills status --global +``` + +Global installs land under `$HOME` (or `$CORVID_SKILLS_HOME` if set), for example +`~/.claude/skills/`, and are tracked in `~/.corvid-skills.json`. They do **not** +replace repository-local installs; a project can still install a different set with +`--repo` / default cwd. + +Add product skills (`let`, `rune`, `augur`, `atlas`, …) only when that tool is actually used. +`update --all` (optionally with `--global`) refreshes skills that are already managed; it +does not install missing ones. + To pin a published catalog release, add its tag to the source, for example: ```sh @@ -62,15 +83,15 @@ The skill content is agent-neutral Markdown. Any agent that can load a `SKILL.md repository context can use it. Fledge currently provides automatic, collision-safe placement for these hosts: -| Host | Repository-local destination | Automatic placement | -| --- | --- | --- | -| Codex | `.codex/skills/` | Yes | -| Claude | `.claude/skills/` | Yes | -| Cursor | `.cursor/skills/` | Yes | -| Gemini | `.gemini/skills/` | Yes | -| Grok | `.grok/skills/` | Yes | -| OpenAI | `.agents/skills/` | Yes | -| Other agents | Agent-defined | No; use the agent's documented skill path. | +| Host | Repo-local (`--repo` / cwd) | Machine-global (`--global`) | Automatic placement | +| --- | --- | --- | --- | +| Codex | `.codex/skills/` | `~/.codex/skills/` | Yes | +| Claude | `.claude/skills/` | `~/.claude/skills/` | Yes | +| Cursor | `.cursor/skills/` | `~/.cursor/skills/` | Yes | +| Gemini | `.gemini/skills/` | `~/.gemini/skills/` | Yes | +| Grok | `.grok/skills/` | `~/.grok/skills/` | Yes | +| OpenAI | `.agents/skills/` | `~/.agents/skills/` | Yes | +| Other agents | Agent-defined | 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. @@ -80,22 +101,23 @@ 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. +Every placement is recorded in `.corvid-skills.json` (repo root or `$HOME` for `--global`) +with its source revision, mode, destination, and content digest. ```sh # Inspect human-readable or machine-readable state. fledge skills status +fledge skills status --global 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 +fledge skills update --all --global --dry-run +fledge skills update --all --global # Preview, then remove one manifest-owned skill. fledge skills uninstall augur --dry-run -fledge skills uninstall augur +fledge skills uninstall augur --global ``` `status` reports `current`, `legacy`, `modified`, or `missing`. A `legacy` OpenAI entry was @@ -143,9 +165,13 @@ The direct installer is available for debugging or environments without plugin d ```sh bin/corvid-skills list --json bin/corvid-skills install agent-coordination --repo /path/to/project --host codex +bin/corvid-skills install agent-coordination --global --host claude bin/corvid-skills status --repo /path/to/project --json +bin/corvid-skills status --global --json bin/corvid-skills update agent-coordination --repo /path/to/project --dry-run +bin/corvid-skills update agent-coordination --global --dry-run bin/corvid-skills uninstall agent-coordination --repo /path/to/project --dry-run +bin/corvid-skills uninstall agent-coordination --global --dry-run ``` ## Design rules @@ -154,4 +180,5 @@ bin/corvid-skills uninstall agent-coordination --repo /path/to/project --dry-run - 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. +- Make installation and lifecycle mutations explicit, manifest-owned, and scoped + (repository-local or machine-global)—never silent. diff --git a/bin/corvid-skills b/bin/corvid-skills index 8a3eaed..15344a1 100755 --- a/bin/corvid-skills +++ b/bin/corvid-skills @@ -7,18 +7,21 @@ manifest_name=".corvid-skills.json" usage() { cat <<'EOF' -Manage shared CorvidLabs agent skills in one repository. +Manage shared CorvidLabs agent skills (repository-local or machine-global). Usage: fledge skills list [--json] - fledge skills install [--repo ] [--host ] [--link] [--dry-run] - fledge skills status [--repo ] [--json] - fledge skills update |--all [--repo ] [--host ] [--dry-run] - fledge skills uninstall [--repo ] [--host ] [--dry-run] + fledge skills install [--repo |--global] [--host ] [--link] [--dry-run] + fledge skills status [--repo |--global] [--json] + fledge skills update |--all [--repo |--global] [--host ] [--dry-run] + fledge skills uninstall [--repo |--global] [--host ] [--dry-run] -Install copies a selected skill into a repository-local agent directory and -records the exact source revision and content digest in .corvid-skills.json. -It never overwrites an existing directory. +Install copies (or links) a selected skill into either: + • a repository-local agent directory, or + • a machine-global host directory under $HOME (or $CORVID_SKILLS_HOME) + +and records the exact source revision and content digest in .corvid-skills.json +(next to that target root). It never overwrites an existing directory. Update and uninstall operate only on unmodified managed copies or exact manifest-owned links. EOF @@ -51,6 +54,33 @@ repository_root() { git -C "$requested" rev-parse --show-toplevel 2>/dev/null || fail "not a Git repository: $requested" } +# Machine-global install root. Override with CORVID_SKILLS_HOME for tests. +skills_home() { + local home="${CORVID_SKILLS_HOME:-${HOME:-}}" + [[ -n "$home" ]] || fail "HOME is unset; cannot use --global" + [[ -d "$home" ]] || fail "skills home is not a directory: $home" + printf '%s' "$home" +} + +# Parent of host skills dir, e.g. .claude/skills -> .claude +host_agent_root() { + dirname "$(host_directory "$1")" +} + +# Parse shared --repo / --global options. Sets: scope_root, is_global +# Remaining args are left in parse_remaining for the caller via a name ref pattern: +# resolve_target_from_flags is called after collecting flags into variables. +resolve_target_root() { + local is_global="$1" + local repo_arg="$2" + if [[ "$is_global" == "true" ]]; then + [[ "$repo_arg" == "." ]] || fail "--global cannot be combined with --repo" + skills_home + else + repository_root "$repo_arg" + fi +} + ensure_safe_install_paths() { local repo="$1" local destination_rel="$2" @@ -123,7 +153,9 @@ resolve_host() { local candidates=() local host for host in codex claude cursor gemini grok openai; do - [[ -d "$repo/$(host_directory "$host")" ]] && candidates+=("$host") + if [[ -d "$repo/$(host_directory "$host")" || -d "$repo/$(host_agent_root "$host")" ]]; then + candidates+=("$host") + fi done if [[ ${#candidates[@]} -eq 1 ]]; then printf '%s' "${candidates[0]}" @@ -458,10 +490,12 @@ install_skill() { local host_arg="auto" local link="false" local dry_run="false" + local is_global="false" while [[ $# -gt 0 ]]; do case "$1" in --repo) [[ $# -ge 2 ]] || fail "--repo needs a path"; repo_arg="$2"; shift 2 ;; + --global) is_global="true"; shift ;; --host) [[ $# -ge 2 ]] || fail "--host needs a value"; host_arg="$2"; shift 2 ;; --link) link="true"; shift ;; --dry-run) dry_run="true"; shift ;; @@ -471,7 +505,7 @@ install_skill() { validate_skill_source "$skill" local repo host destination destination_rel revision digest manifest - repo="$(repository_root "$repo_arg")" + repo="$(resolve_target_root "$is_global" "$repo_arg")" host="$(resolve_host "$repo" "$host_arg")" destination_rel="$(host_directory "$host")/$skill" destination="$repo/$destination_rel" @@ -515,9 +549,11 @@ update_skills() { local repo_arg="." local host_filter="" local dry_run="false" + local is_global="false" while [[ $# -gt 0 ]]; do case "$1" in --repo) [[ $# -ge 2 ]] || fail "--repo needs a path"; repo_arg="$2"; shift 2 ;; + --global) is_global="true"; shift ;; --host) [[ $# -ge 2 ]] || fail "--host needs a value"; host_filter="$2"; shift 2 ;; --dry-run) dry_run="true"; shift ;; *) fail "unknown option: $1" ;; @@ -528,7 +564,7 @@ update_skills() { [[ -z "$host_filter" ]] || host_directory "$host_filter" >/dev/null local repo manifest revision - repo="$(repository_root "$repo_arg")" + repo="$(resolve_target_root "$is_global" "$repo_arg")" manifest="$repo/$manifest_name" [[ -f "$manifest" && ! -L "$manifest" ]] || fail "managed-skills manifest not found: $manifest" revision="$(git -C "$root_dir" rev-parse --verify HEAD 2>/dev/null || printf 'working-tree')" @@ -607,9 +643,11 @@ uninstall_skill() { local repo_arg="." local host_filter="" local dry_run="false" + local is_global="false" while [[ $# -gt 0 ]]; do case "$1" in --repo) [[ $# -ge 2 ]] || fail "--repo needs a path"; repo_arg="$2"; shift 2 ;; + --global) is_global="true"; shift ;; --host) [[ $# -ge 2 ]] || fail "--host needs a value"; host_filter="$2"; shift 2 ;; --dry-run) dry_run="true"; shift ;; *) fail "unknown option: $1" ;; @@ -618,7 +656,7 @@ uninstall_skill() { [[ -z "$host_filter" ]] || host_directory "$host_filter" >/dev/null local repo manifest - repo="$(repository_root "$repo_arg")" + repo="$(resolve_target_root "$is_global" "$repo_arg")" manifest="$repo/$manifest_name" [[ -f "$manifest" && ! -L "$manifest" ]] || fail "managed-skills manifest not found: $manifest" local manifest_output="" @@ -683,22 +721,28 @@ uninstall_skill() { status_skills() { local repo_arg="." local json="false" + local is_global="false" while [[ $# -gt 0 ]]; do case "$1" in --repo) [[ $# -ge 2 ]] || fail "--repo needs a path"; repo_arg="$2"; shift 2 ;; + --global) is_global="true"; shift ;; --json) json="true"; shift ;; *) fail "unknown option: $1" ;; esac done local repo manifest - repo="$(repository_root "$repo_arg")" + repo="$(resolve_target_root "$is_global" "$repo_arg")" manifest="$repo/$manifest_name" [[ ! -L "$manifest" ]] || fail "refusing symlinked manifest: $manifest" if [[ ! -f "$manifest" ]]; then if [[ "$json" == "true" ]]; then printf '{"schema_version":1,"installs":[]}\n' else - echo "No managed CorvidLabs skills are installed in $repo" + if [[ "$is_global" == "true" ]]; then + echo "No managed CorvidLabs skills are installed globally in $repo" + else + echo "No managed CorvidLabs skills are installed in $repo" + fi fi return fi diff --git a/skills/agent-3md/SKILL.md b/skills/agent-3md/SKILL.md index 5a78f7c..1b4d612 100644 --- a/skills/agent-3md/SKILL.md +++ b/skills/agent-3md/SKILL.md @@ -5,25 +5,77 @@ description: Validate, route, inspect, or run agent.3md manifests and typed tool # Agent 3md -Let can locate an `agent.3md`; this skill validates and routes it. Treat the file as executable configuration. +An `agent.3md` is executable configuration: plane 0 is identity; other planes are skills +with triggers, typed inputs, optional `tool=` command templates, and dependency links. +Let can **locate** the file; this skill **validates, routes, and optionally runs** it. -## Validate and preview +## Install + +CorvidLabs/agent-3md is **not** a Fledge plugin (no `fledge agent3md`). Use the library +or CLI below. + +**TypeScript library** (embed): + +```sh +npm install @corvidlabs/agent3md +# or: bun add @corvidlabs/agent3md +``` + +**CLI** (prefer current main; crates.io may lag for `run`/`--exec`): + +The Rust CLI on GitHub main supports `manifest`, `skills`, `route`, `get`, `resolve`, +`validate`, and `run` (`--exec`). Published `cargo install agent3md` may ship only the +inspect/validate subset—verify `agent3md --help` after install. + +```sh +# From a clone of CorvidLabs/agent-3md +cd /path/to/agent-3md +cargo install --path loaders/rust +# or without a global install: +bun run cli --help +``` + +Inside the agent-3md repo: + +| Action | Command | +| --- | --- | +| Inspect / route / run | `bun run cli …` | +| Validate | `bun run validate ` (not `bun run cli validate`) | +| Scaffold | `bun run cli new …` (TS-only) | + + +## Inspect without executing ```sh -cargo install agent3md agent3md validate agent.3md -agent3md run agent.3md "" key=value +agent3md manifest agent.3md +agent3md skills agent.3md +agent3md route agent.3md "" +agent3md get agent.3md +agent3md resolve agent.3md ``` -The default `run` prints the selected command without executing it. Inspect the matched route, -substituted values, quoting, working directory, and referenced paths before taking action. +If `validate` rejects a modern manifest after `cargo install agent3md` from crates.io, use +repo-local `bun run validate` or a git/`--path` install of the current loader—published +crates.io **0.1.0** still requires `model:` in frontmatter and does not ship `run`/`--exec`. -## Execute only when authorized +## Preview, then execute only when authorized + +Confirm `run` exists in `agent3md --help` first: ```sh +# Route + fill tool template; print the command (does not run it) +agent3md run agent.3md "" key=value + +# Run the rendered command agent3md run agent.3md "" key=value --exec ``` -Use `--exec` only when the rendered command is within the user's authorization. It does not bypass Fledge workflows, -repository policy, the sandbox, or external-write approval. Prefer `fledge run` for repository-declared tasks. Use the -`three-md` skill for general documents that are not executable agent manifests. +Repo-local equivalent: `bun run cli run agent.3md "" key=value [--exec]`. + +Inspect the matched skill, substituted values, quoting, working directory, and referenced +paths before `--exec`. `--exec` does not bypass Fledge workflows, repository policy, the +sandbox, or external-write approval. Prefer `fledge run` for repository-declared tasks. + +Skills without a `tool=` attribute are playbook-only—follow them with the host's own tools. +Use the `three-md` skill for general `.3md` documents that are not agent manifests. diff --git a/skills/agent-coordination/SKILL.md b/skills/agent-coordination/SKILL.md index 87062d6..33b323e 100644 --- a/skills/agent-coordination/SKILL.md +++ b/skills/agent-coordination/SKILL.md @@ -5,13 +5,24 @@ description: Coordinate CorvidLabs agents through discovery, observation, execut # Agent Coordination -Use this skill before asking an agent for status, intervening in its work, or choosing a -worktree for an agent task. +Use this skill as the hub before asking an agent for status, intervening in its work, or +choosing a worktree. Product detail lives in sibling skills: `let`, `rune`, +`fledge-workflows`, and `spec-sync` / `spec-sync-routing`. -## Discover first +## Sequence -For public-only work, establish facts from the confirmed repository without invoking Let's -federated discovery: +1. **Discover** the repository, worktree, and (when authorized) session owner. +2. **Observe** a confirmed CLI session before sending anything. +3. **Execute** only through the repository's declared Fledge tasks and lanes. +4. **Verify** with Spec Sync (when the repo uses it), then Git, PR, and CI. + +Do not skip ahead on session titles or branch names alone. + +## Discover + +### Public-only work + +Stay inside the confirmed repository. Do not invoke Let: ```sh fledge work status @@ -20,40 +31,35 @@ git status --short --branch git ls-files ``` -Read only tracked instructions and declared workflows. Do not infer ownership from a branch -name alone. Session metadata is an activity hint, not proof that work is delivered: compare it -with the worktree, commits, pull request, CI, and sandbox. +Read only tracked instructions and declared workflows. Mark Let discovery **blocked** and +continue with repository evidence. Let 0.2 project-scope finds still pull user catalogs for +skills/agents (and related kinds) by default, and `where`/worktrees can list siblings; do +not filter private results after they have already been read. Details and kind matrix: `let` +skill. -Let 0.2 can return user-global or sibling-worktree metadata even for project-scoped queries. -Do not invoke it in a public-only workflow until the installed version is independently verified -to isolate the requested repository. Mark the Let step blocked and continue with public -repository evidence; do not filter private results after they have already been read. +### Authorized local metadata -When local agent metadata is explicitly authorized, use `fledge let --help` to select the -narrowest supported query and treat every returned path or session identifier as private. +When the task explicitly permits local agent metadata, use the `let` skill with the +narrowest supported query (prefer `find worktrees` / `find sessions` with +`--scope project`). Treat every returned path and session id as private until public +provenance is proven independently. Do not run Let workbed write commands unless writes +are authorized. -## Observe by default +## Observe, then intervene -Use `fledge rune watch` to open a confirmed CLI-agent session in a live PTY and observe -current work before sending anything. For a bounded, non-interactive inspection, use -`run` with a short timeout instead. +Confirm repository, worktree, session, and active task first. Use the `rune` skill +(and `fledge rune run|watch --help` for the installed flag set): -```sh -fledge rune run --timeout=60 -- --resume -fledge rune watch -- --resume -``` +- `fledge rune run --timeout=30 --json -- …` — bounded, non-interactive +- `fledge rune watch --log= -- …` — live PTY; keystrokes go here -## Intervene narrowly - -Only message an agent after confirming its session and active task. Send one scoped, -non-conflicting instruction. Do not interrupt tests, commits, pushes, or an independent -review merely to ask for a status update; inspect the worktree, PR, and CI instead. +Public Rune has no separate `send` subcommand. Send **one** scoped instruction only after +observation, and never while tests, commits, pushes, migrations, or independent review +are in progress—inspect Git and CI instead. Never drive the same session from two +operators, and never start a second agent in a worktree that already has an owner. ## Execute through Fledge -After discovery and observation establish the correct repository and scope, inspect its -declared automation and run only the exact task or lane needed: - ```sh fledge run --list fledge lanes list @@ -61,27 +67,28 @@ fledge run fledge lanes run ``` -Do not translate a repository workflow into ad hoc shell commands when Fledge already -declares it. Preserve the task output and revision as execution evidence. +Prefer declared tasks and lanes over ad hoc shell. Record task output with the exact +revision. Details: `fledge-workflows` skill. -## Verify with Spec Sync +## Verify -If the repository uses Spec Sync, read its generated local skill and installed CLI version -before choosing commands. Run the exact project-defined coverage or check command after the -Fledge task. A successful task is not proof that specifications cover the change, and a -Spec Sync failure must not be hidden by approving or rewriting scope without the user. +- If the repository uses Spec Sync, follow `spec-sync-routing` to the generated local + skill; use shared `spec-sync` only for version-neutral principles. +- Spec Sync closing flow is **accept → merge → archive after merge** (not archive in the + delivery PR before merge). Details: `spec-sync` skill. +- A green Fledge task is not proof that specs cover the change. +- After any intervention, re-check worktree, PR, CI, and sandbox. Session text is an + activity hint, not delivery. -## Verify and recover +## Evidence hierarchy -After a prompt is accepted, verify the worktree, declared Fledge workflow, Spec Sync evidence, -and CI again; delivery is not completion. If -the target session or worktree is wrong, stop and rediscover it within the task's privacy scope. If a provider or -network connection fails, Rune cannot bypass it—report the boundary and rely on repository -evidence. Assign one worktree and responsibility per agent, and use sibling-worktree context -to avoid overlapping edits. For repeated CI failures, reproduce narrowly and add or confirm a -regression rather than repeatedly sending broad retry prompts. +Highest trust first: committed tree and CI on that SHA → PR and review → Fledge/Spec Sync +results on that SHA → worktree diff → Rune/session output → Let session cards. -## Source of truth +## Recover -Session metadata describes activity. The worktree, commit history, pull request, CI, -and sandbox results determine whether work is complete. +- Wrong session or worktree: stop; rediscover within the task's privacy scope. +- Provider or network failure: Rune cannot bypass it; report the boundary. +- Repeated CI failure: reproduce narrowly and add or confirm a regression—do not spam + retry prompts into a live session. +- One worktree and one responsible agent per task. diff --git a/skills/atlas/SKILL.md b/skills/atlas/SKILL.md index 8fff4a2..b34cf76 100644 --- a/skills/atlas/SKILL.md +++ b/skills/atlas/SKILL.md @@ -7,24 +7,46 @@ description: Inspect spec ownership, drift, coverage, review queues, and gaps wi Atlas maps code to specifications. A spec-less result is valid evidence, not a command failure. -## Inspect first +## Install + +Atlas is a Fledge plugin: ```sh fledge plugins install CorvidLabs/fledge-plugin-atlas fledge atlas --help +``` + +## Inspect first (agent-friendly JSON) + +```sh fledge atlas . --json -fledge atlas . --review --json -fledge atlas . --owns --json -fledge atlas . --since --json -fledge atlas . --spec --json +fledge atlas . --review +fledge atlas . --owns +fledge atlas . --since +fledge atlas . --spec +fledge atlas . --gaps ``` -Use `--gaps ` only with an existing LCOV report. Record the repository revision -and input report with findings. +Agent modes (`--review`, `--owns`, `--since`, `--spec`, `--gaps`) already print JSON; an +extra `--json` is unnecessary for those modes. + +`--gaps` prints a coverage-gap worklist. It is a **boolean**—it does not take an LCOV path. +The optional path argument is the **project root**. LCOV is auto-discovered, first match +wins among: `lcov.info`, `coverage/lcov.info`, `coverage/lcov-report/lcov.info`, +`target/llvm-cov/lcov.info`, `target/coverage/lcov.info`, `target/tarpaulin/lcov.info`. +Without a report, the result is `{ "note": "no lcov coverage found", "gaps": [] }` (not a +failure). Record the repository revision with findings. + +Other helpers: `--svg ` for a single SVG on stdout. Current product supports +`coverage`, `langmix`, `treemap`, `sunburst`, and `calendar`—confirm the installed list +with `fledge atlas --help` (older builds may advertise only the first three). ## Generate deliberately -Default output, `--3md`, `--timeline`, and `-o ` can write files. `--scaffold` prints a -draft to standard output. Preview before writing, choose an explicit destination, and inspect -the result. When Atlas creates Spec Sync material, follow the repository-generated Spec Sync -skill for validation and lifecycle policy. +Default HTML, `--3md`, and `--timeline` write files under the **current working directory** +(for example `.atlas.html`), not necessarily inside the analyzed project root. +`-o ` sets an explicit HTML destination. `--scaffold` prints a draft `*.spec.md` +skeleton to standard output. Preview before writing, choose an explicit destination, and +inspect the result. When Atlas creates Spec Sync material, follow the repository-generated +Spec Sync skill for validation and lifecycle policy. Validate Atlas-generated `.3md` with +the `three-md` skill before treating it as project truth. diff --git a/skills/attest/SKILL.md b/skills/attest/SKILL.md index f165524..4050a46 100644 --- a/skills/attest/SKILL.md +++ b/skills/attest/SKILL.md @@ -5,31 +5,59 @@ description: Verify or record reviewed commit provenance, policy gates, and audi # Attest -Attest records review evidence for exact commits. The public plugin is currently macOS-only. +Attest records review evidence for exact commits in Git notes (`refs/notes/attest`). Signing +is optional—an unsigned attestation is still a valid local record. -## Verify before writing +## Install + +Use the Fledge plugin repo `CorvidLabs/fledge-plugin-attest` (not the standalone `attest` +kit alone). The public Fledge plugin targets **macOS 13+**. ```sh fledge plugins install CorvidLabs/fledge-plugin-attest fledge attest --help +fledge attest help sign +fledge attest help verify +``` + +## Verify before writing + +```sh fledge attest log -C . --json -fledge attest verify -C . --commit --policy --json -fledge attest verify -C . --range .. --policy --json +fledge attest verify -C . --commit --json +fledge attest verify -C . --range .. --json ``` -Treat a missing or failed attestation as evidence to investigate, not permission to fabricate one. +Policy loads from `.attest.json` in the current working directory when present. Override +with `--policy ` only when using a non-default file (the path must exist). Treat a +missing or failed attestation as evidence to investigate, not permission to fabricate one. ## Record proven evidence -Sign the exact reviewed SHA only after the verdict, confidence, tests, and reviewer identity are known: +Sign or record the exact reviewed SHA only after the verdict, confidence, tests, and +reviewer identity are known: ```sh fledge attest sign -C . --commit --reviewer --confidence <0-to-1> \ - --verdict --note --sign --json + --verdict --note --json + +# Optional cryptographic signature (requires a signing key; generate with +# `fledge attest keygen` when that subcommand is present on the installed plugin) +fledge attest sign -C . --commit --reviewer --confidence <0-to-1> \ + --verdict proceed --sign --json + +# Optional: fold in prior Augur JSON (file path or `-` for stdin) +fledge attest sign -C . --commit --reviewer --from-augur --json ``` -Add `--tests-passed` or `--human-approved` only when each statement is true. Signing requires -configured key material and authorization. Attestations live in Git notes under -`refs/notes/attest`; publishing those notes is a separate remote write. +Add `--tests-passed` or `--human-approved` only when each statement is true. Publishing +`refs/notes/attest` is a separate remote write from creating the local note. + +`export` always emits JSON (no `--json` flag): + +```sh +fledge attest export -C . +fledge attest export -C . --range .. --policy .attest.json +``` -Use `fledge attest export -C . --json` for an audit artifact, and preserve the commit SHA with every result. +Preserve the commit SHA with every result. diff --git a/skills/augur/SKILL.md b/skills/augur/SKILL.md index 1602cf3..bfcca10 100644 --- a/skills/augur/SKILL.md +++ b/skills/augur/SKILL.md @@ -5,26 +5,47 @@ description: Assess working-tree, staged, range, or CI change risk and gates wit # Augur -Use Augur for deterministic change-risk evidence. It supplements tests and review; it does not approve a change. +Use Augur for deterministic change-risk evidence (churn, coupling, test gaps, sensitive +paths, ownership, revert history). Verdicts are `proceed`, `review`, or `block`. It +supplements tests and review; it does not approve a change. No API key or LLM required. -## Inspect risk +## Install + +Use the Fledge plugin repo `CorvidLabs/fledge-plugin-augur` (not the standalone `augur` +kit alone). The public plugin targets **macOS 13+**. Confirm with `fledge augur --help` +after install. ```sh fledge plugins install CorvidLabs/fledge-plugin-augur fledge augur --help +fledge augur help check +fledge augur help gate +``` + +## Inspect risk + +```sh fledge augur check -C . --json fledge augur check -C . --staged --json fledge augur check -C . --range .. --json +fledge augur check -C . --verbose --json ``` -`check` reports findings but exits successfully. Working-tree and staged diffs do not include -untracked files, so inventory those separately before relying on a clean report. +`check` reports findings but exits successfully. Default scope is the working-tree diff. +Working-tree assessment **includes** non-ignored untracked files. **Staged** and **range** +scopes do not—inventory untracked files separately before relying on a clean staged or +range report. ## Enforce a gate ```sh fledge augur gate -C . --threshold review --json fledge augur gate -C . --threshold block --json +fledge augur gate -C . --range .. --threshold review --json ``` -`gate` exits nonzero when the selected threshold is met. Record the exact revision and scope with the result. +Thresholds: `proceed`, `review` (default), or `block`. `gate` exits nonzero when the +verdict meets or exceeds the selected threshold. Record the exact revision and scope with +the result. + +To attach Augur output when recording provenance, see the `attest` skill (`--from-augur`). diff --git a/skills/ci-release-hygiene/SKILL.md b/skills/ci-release-hygiene/SKILL.md index bb93fdf..7cc7f83 100644 --- a/skills/ci-release-hygiene/SKILL.md +++ b/skills/ci-release-hygiene/SKILL.md @@ -10,25 +10,50 @@ ready. ## Identify the revision -First confirm the PR head and the revision that each CI run tested. A red run on an old -commit is stale evidence, not a failure of the current local repair; a green run on an -old commit is not approval for later changes. Say which case applies before acting. +First confirm the PR head and the revision that each CI run tested: + +```sh +git rev-parse HEAD +git status --short --branch +fledge work status +``` + +A red run on an old commit is stale evidence, not a failure of the current local repair; a +green run on an old commit is not approval for later changes. Say which case applies before +acting. ## Before push -Run the repository's relevant Fledge verification lane from the current committed tree. -Do not assume one command fits every project. Keep the lane focused while iterating, and -run the project-required full or release lane before declaring a PR ready. +Run the repository's relevant Fledge verification lane from the **current committed tree** +(commit first when the lane must match what CI will see). Discover the lane—do not assume +one command fits every project: + +```sh +fledge run --list +fledge lanes list +fledge lanes run +``` + +Keep the lane focused while iterating, and run the project-required full or release lane +before declaring a PR ready. When configured, deterministic risk gates (`augur`) and +provenance checks (`attest`) belong on the same SHA you intend to push. ## Before tag or release -Require evidence for the exact release candidate: committed-tree verification, required -hosted CI, version/release validation, and any configured trust or attestation checks. +Require evidence for the exact release candidate: + +- verification on the committed tree at the candidate SHA +- required hosted CI green on that SHA +- version / changelog / release validation the repo declares +- any configured trust or attestation checks on that SHA + Do not tag from uncommitted work or rely on verification evidence produced before the -final release-candidate commit. +final release-candidate commit. Prefer the repository's `fledge release` flow and its verify/release-style lanes (discover +via `fledge lanes list`) when present—lane names are repository-defined, not universal. +After a release bump creates a new commit, re-verify **that** SHA—not the pre-bump tree. ## Communicate state clearly Separate: local checks passed, CI running, CI failed on current head, and CI stale on a previous head. Give one concrete next action rather than treating every CI transition as -a blocker. +a blocker. For private→public readiness, use `public-release-audit`. diff --git a/skills/corvid-swift-package/SKILL.md b/skills/corvid-swift-package/SKILL.md index 62c6dcf..257948e 100644 --- a/skills/corvid-swift-package/SKILL.md +++ b/skills/corvid-swift-package/SKILL.md @@ -5,16 +5,16 @@ description: Build, modify, test, review, or release CorvidLabs Swift packages w # CorvidLabs Swift Package -Use this skill for a Swift package owned by CorvidLabs. It is a shared operating baseline; -the repository's `AGENTS.md`, `Package.swift`, local skills, and CI configuration win whenever -they are more specific. +Use this skill for a Swift package owned by CorvidLabs. It is a shared operating baseline, +not a substitute for product CLIs. The repository's `AGENTS.md`, `Package.swift`, local +skills, and CI configuration win whenever they are more specific. ## Discover before changing code Start with the repository's instructions and Fledge surface. Use the native task or lane when -one exists; use `fledge introspect`, `fledge --help`, or `fledge plugins list` before falling -back to direct `swift` or `git` commands. Read the affected target, tests, platform conditions, -and public API before proposing a change. +one exists; use `fledge introspect`, `fledge --help`, `fledge run --list`, or +`fledge plugins list` before falling back to direct `swift` or `git` commands. Read the +affected target, tests, platform conditions, and public API before proposing a change. ## Preserve package guarantees @@ -23,30 +23,36 @@ and public API before proposing a change. `private`). Use `open` only for externally subclassable or overridable API and `package` only for package-scoped implementation API. Public API is explicit and documented. Local declarations do not admit access modifiers. +- Prefer descriptive generic parameters (`Value`, `Output`, `Key`) over single letters. - Treat Swift 6 strict concurrency as a design constraint. Values shared across isolation domains are `Sendable`; ownership-transferred values may use Swift's `sending` and region-based isolation. Isolate mutable state with actors by default, or use a safe synchronization primitive when the repository's synchronous API requires one. Asynchronous APIs use `async`/`await`. For a Swift-5.9-compatible manifest, enable complete checking with `swiftSettings: [.enableExperimentalFeature("StrictConcurrency")]`, but do not treat warnings - in Swift 5 language mode as a release gate. Require a Swift 6 language-mode build, or an explicit - warnings-as-errors CI equivalent, so concurrency violations fail verification. -- Do not add force unwraps, `try!`, `as!`, callback APIs, or `@unchecked Sendable` merely to make - a build pass. Explain and isolate an unavoidable exception in review. -- Keep targets portable across the package's declared Apple, Linux, and Windows platforms. - Gate platform APIs with conditional compilation and provide a real fallback where the contract - requires one. + in Swift 5 language mode as a release gate. Prefer Swift 6 tools / language mode; require a + Swift 6 language-mode build, or an explicit warnings-as-errors CI equivalent, so concurrency + violations fail verification. +- **Never** use force unwrap (`!`), `try!`, or `as!` in library code. Do not use callback APIs + or `@unchecked Sendable` merely to make a build pass. Test-only or explicitly documented + exceptions require review justification. +- Keep targets portable across the platforms **declared in `Package.swift` and actually + verified in CI**. Read those sources before claiming multi-platform readiness—do not assume + Windows (or any platform) unless declared and gated. When non-macOS platforms are claimed, + do not treat a macOS-only build as a release gate. +- Prefer Apple frameworks and minimal dependencies; do not add a package dependency when the + platform already provides the capability. ## Verify the actual release surface Run the repository's Fledge test/release lane first. Cover the changed behavior with focused tests, then run the package's required cross-platform or CI-equivalent lane before publishing. Check the release artifact and public documentation when an exported API, platform support, or -version changes. When a package declares non-macOS platforms, do not claim a release is ready -from a macOS-only build. +version changes. ## Keep reviews actionable In a PR, state the changed contract, platform/concurrency impact, and exact validation run. If the package has a generated Spec Sync skill, use it for the change record and bidirectional -checks; this skill does not replace that lifecycle. +checks; this skill does not replace that lifecycle. For push/tag evidence language, use +`ci-release-hygiene`. diff --git a/skills/corvid-web-bun/SKILL.md b/skills/corvid-web-bun/SKILL.md index c59a5e0..f393fd4 100644 --- a/skills/corvid-web-bun/SKILL.md +++ b/skills/corvid-web-bun/SKILL.md @@ -5,28 +5,32 @@ description: Build, modify, test, review, or release CorvidLabs Bun web projects # CorvidLabs Web with Bun -Use Bun and the repository's Fledge tasks. This is a shared operating baseline, not a -replacement for a repository's `AGENTS.md`, framework conventions, or product specs. +Use Bun and the repository's Fledge tasks when the project declares them. This is a shared +operating baseline, not a replacement for a repository's `AGENTS.md`, framework conventions, +product specs, or an existing non-Bun package manager. ## Start with the project -1. Confirm the current public repository and its tracked instructions before editing: +1. Confirm the repository root and its tracked instructions before editing: ```sh fledge work status fledge run --list + fledge introspect --json git status --short --branch git ls-files ``` - Do not use federated Let discovery in public-only work: Let 0.2 can enumerate user-global - or sibling-worktree metadata even for project-scoped queries. + In public-only or public-evidence work, do not use federated Let discovery (project-scope + still pulls user skill catalogs by default). When local agent metadata is explicitly + authorized, use the `let` skill. -2. Read the project instructions, `package.json`, and the affected spec or component. +2. Read the project instructions, `package.json` / lockfile, and the affected spec or component. 3. Use the Fledge task named by the project. Inspect available tasks if it is unclear: ```sh fledge run --help + fledge lanes list fledge lanes --help ``` @@ -36,9 +40,11 @@ defines an authoritative lane. ## Build with Bun - Use Bun for dependencies and scripts when `package.json`, the lockfile, and local instructions - declare Bun. Preserve another explicitly selected package manager, especially in workspaces; + declare Bun. Prefer `bun install`, `bun test`, `bun run