From 29470d3c7d8caa49ab8e869619890c4e9abd559b Mon Sep 17 00:00:00 2001 From: 0xLeif Date: Sat, 1 Aug 2026 21:12:12 -0600 Subject: [PATCH 1/5] Update: verify skill content against product CLIs Cross-check every catalog skill against live Fledge plugins and product repos, then fix wrong flags, lifecycle guidance, install paths, and host prompt stubs so agents get accurate public commands. --- skills/agent-3md/SKILL.md | 68 +++++++++++++++--- skills/agent-coordination/SKILL.md | 103 ++++++++++++++------------- skills/atlas/SKILL.md | 42 +++++++---- skills/attest/SKILL.md | 48 +++++++++---- skills/augur/SKILL.md | 29 ++++++-- skills/ci-release-hygiene/SKILL.md | 45 +++++++++--- skills/corvid-swift-package/SKILL.md | 38 +++++----- skills/corvid-web-bun/SKILL.md | 25 ++++--- skills/fledge-workflows/SKILL.md | 50 ++++++++++--- skills/let/SKILL.md | 94 +++++++++++++++++------- skills/public-release-audit/SKILL.md | 33 ++++++--- skills/rune/SKILL.md | 75 +++++++++++++------ skills/spec-sync-routing/SKILL.md | 25 +++++-- skills/spec-sync/SKILL.md | 63 +++++++++------- skills/three-md/SKILL.md | 30 +++++--- 15 files changed, 541 insertions(+), 227 deletions(-) diff --git a/skills/agent-3md/SKILL.md b/skills/agent-3md/SKILL.md index 5a78f7c..b0e4e29 100644 --- a/skills/agent-3md/SKILL.md +++ b/skills/agent-3md/SKILL.md @@ -5,25 +5,73 @@ 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 + +**TypeScript library** (embed; npm latest is the library path): + +```sh +npm install @corvidlabs/agent3md +# or: bun add @corvidlabs/agent3md +``` + +**CLI (prefer current main, not a stale crates.io-only install for `run`):** + +The Rust CLI on GitHub main supports `manifest`, `skills`, `route`, `get`, `resolve`, +`validate`, and `run` (`--exec`). Published `cargo install agent3md` may lag and ship only +the inspect/validate subset without `run`/`--exec`—verify `agent3md --help` after install. + +```sh +# From a clone of CorvidLabs/agent-3md (current surface) +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`. + +## Preview, then execute only when authorized -## 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..6307364 100644 --- a/skills/atlas/SKILL.md +++ b/skills/atlas/SKILL.md @@ -7,24 +7,42 @@ 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 - ```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..e378587 100644 --- a/skills/attest/SKILL.md +++ b/skills/attest/SKILL.md @@ -5,31 +5,55 @@ 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. - -## Verify before writing +Attest records review evidence for exact commits in Git notes (`refs/notes/attest`). The +public Fledge plugin targets **macOS 13+** (no Linux/Windows plugin support). Signing is +optional—an unsigned attestation is still a valid local record. ```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..d9a6783 100644 --- a/skills/augur/SKILL.md +++ b/skills/augur/SKILL.md @@ -5,26 +5,45 @@ 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 +The public Fledge plugin (`fledge-plugin-augur`) targets **macOS 13+**. The standalone +`augur` CLI may support additional platforms; this skill documents the Fledge entrypoint +only. 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