Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .agents/skills/agent-conduct/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@ Read `GOVERNANCE.md` "Verification Discipline" before reporting success on anyth
- **Run the repo's whole lint gate before every push**, not the parts that look relevant, because the tool most likely to catch a change is often the one it seems least about.
- **A launched process is not a result.** Report the output the wait produced, and where it produced none, that absence is the report. Never name an external cause the record does not carry.
- **A local clone is not the branch it names.** Fetch immediately before reading, or read the live ref, and name the ref and commit in any finding a local read produced.
- **A "does not exist" claim names the branch it was checked against.** A worktree's default branch is not necessarily the one the content lives on: in-flight content on a `release`-model repo lands on `develop` before `main`, per `GOVERNANCE.md` "Branching Model," so check that branch before reporting anything absent repo-wide.
- **A test asserts the mechanism it names, and a gate has to be watched failing.** A case that passes for an incidental reason is worse than no case, because it is later cited as evidence.

Claims about a pull request being reviewed, clean, or mergeable are owned by the `pr-review-conduct` skill, and claims that a commit landed by `git-commit-conventions`.
Expand Down
6 changes: 6 additions & 0 deletions .agents/skills/operational-vs-release-workflow/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,12 @@ rather than guessing from the repo's contents.

## Branching (release model)

- **GitHub's repository setting for "default branch" reads `main`, but `develop` is where work
starts and where in-flight content lives.** A worktree or clone that defaults to "the default
branch" lands on `main` and can silently miss content that has merged to `develop` but not yet
been promoted. Before branching off, cloning for, or asserting something absent from this repo,
check `develop`, not just whichever branch a tool defaulted to. See GOVERNANCE.md "Verification
Discipline" on naming the branch a "does not exist" claim was checked against.
- `develop` is the integration branch. Feature branches -> `develop` is **squash-only**, which
keeps `develop` linear.
- `develop -> main` is **merge-commit only** (no squash, no rebase). Merge commits preserve
Expand Down
2 changes: 1 addition & 1 deletion .claude-plugin/fleet-skills/.source-digest
Original file line number Diff line number Diff line change
@@ -1 +1 @@
f9e5473792ab198e
45204450870e4fb2
1 change: 1 addition & 0 deletions .claude-plugin/fleet-skills/skills/agent-conduct/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@ Read `GOVERNANCE.md` "Verification Discipline" before reporting success on anyth
- **Run the repo's whole lint gate before every push**, not the parts that look relevant, because the tool most likely to catch a change is often the one it seems least about.
- **A launched process is not a result.** Report the output the wait produced, and where it produced none, that absence is the report. Never name an external cause the record does not carry.
- **A local clone is not the branch it names.** Fetch immediately before reading, or read the live ref, and name the ref and commit in any finding a local read produced.
- **A "does not exist" claim names the branch it was checked against.** A worktree's default branch is not necessarily the one the content lives on: in-flight content on a `release`-model repo lands on `develop` before `main`, per `GOVERNANCE.md` "Branching Model," so check that branch before reporting anything absent repo-wide.
- **A test asserts the mechanism it names, and a gate has to be watched failing.** A case that passes for an incidental reason is worse than no case, because it is later cited as evidence.

Claims about a pull request being reviewed, clean, or mergeable are owned by the `pr-review-conduct` skill, and claims that a commit landed by `git-commit-conventions`.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,12 @@ rather than guessing from the repo's contents.

## Branching (release model)

- **GitHub's repository setting for "default branch" reads `main`, but `develop` is where work
starts and where in-flight content lives.** A worktree or clone that defaults to "the default
branch" lands on `main` and can silently miss content that has merged to `develop` but not yet
been promoted. Before branching off, cloning for, or asserting something absent from this repo,
check `develop`, not just whichever branch a tool defaulted to. See GOVERNANCE.md "Verification
Discipline" on naming the branch a "does not exist" claim was checked against.
- `develop` is the integration branch. Feature branches -> `develop` is **squash-only**, which
keeps `develop` linear.
- `develop -> main` is **merge-commit only** (no squash, no rebase). Merge commits preserve
Expand Down
10 changes: 8 additions & 2 deletions GOVERNANCE.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,8 +57,13 @@ Two workflow models, set per repo by the registry `workflowModel` field. Most re
`release`: squash-only feature branches into `develop`, merge-commit-only `develop -> main`
promotions, forward-only with no back-merges, and two promotion traps worth knowing before the
first one (never delete `develop`, resolve an EOL-only conflict by taking `develop`'s side).
**Operational** repos differ substantially (direct-to-`develop`, advisory CI, dispatch-only
release), covered as a delta rather than a separate model.
**GitHub's own "default branch" repository setting reads `main`, but `develop` is where work
starts and where in-flight content lives**, so a worktree or clone that defaults to "the default
branch" lands on `main` and can silently miss content already merged to `develop` but not yet
promoted. Branch from `develop` for a `release`-model repo unless the task is explicitly about
`main`-only content. **Operational** repos differ substantially
(direct-to-`develop`, advisory CI, dispatch-only release), covered as a delta rather than a
separate model.

This is packaged as the `operational-vs-release-workflow` Skill at
`.agents/skills/operational-vs-release-workflow/SKILL.md` in the hub, not a repo-relative link
Expand Down Expand Up @@ -166,6 +171,7 @@ The checks that separate work actually done from work that merely reports succes
- **Never edit an active `.code-workspace` file.** A workspace file rewritten on disk can make VS Code reload the window, and a reload destroys the running agent session's context, so the work in flight is lost with nothing to catch it, and the trigger is not fully characterized (an agent's edit has caused the reload where a human's identical edit did not). Surface the needed change for the maintainer to apply by hand.
- **A green check is not evidence the work happened.** A skipped job and a passing job are indistinguishable in the aggregated required check. When a job exists to exercise something, confirm from its log that it ran and produced the output it promises.
- **A local clone is not the branch it names, it is whatever that clone last fetched.** Reading a checkout on disk answers what that clone last saw, so a finding taken from one carries a date nobody stated, and two failures of exactly that shape are on record from one session: a repository reported as still drifted on a file whose fix had already merged, and a repository reported as missing a file it carries because the checkout sat on an older branch. Read the live ref through the API where the claim will be acted on, or fetch immediately before reading, and name the ref and the commit in any finding a local read produced. A clone stays the right tool for anything needing history or a build, which an API read cannot give.
- **A "does not exist" claim names the branch it was checked against.** A worktree or checkout answers for whichever ref it was built from, and that ref is not necessarily the one the content lives on: a `release`-model repo carries in-flight content on `develop`, per "Branching Model" above, well before it reaches `main`, so a worktree defaulted to the fleet's default branch can hold nothing while the repository holds everything. Before reporting a file, a directory, or a piece of content as absent anywhere in a repo, check it against the branch the repo's own model designates as current for that kind of content, not only whichever branch a worktree or checkout happened to default to, and name the branch the negative claim was checked against in the finding itself.
- **A launched process is not a result, and a cause nobody observed is not a diagnosis.** "The watcher is armed" names a process rather than a finding, so what gets reported is the output that process produced, and where it produced none, that absence is the report. The failure it prevents is an agent standing still on a condition that was met half an hour earlier, having announced the wait and never read it. Naming an external cause for such a stall afterwards, a throttle or a quota that appears nowhere in the record, turns a local defect into a story about someone else and closes the investigation on the wrong party, so read the record for the cause before naming one, and where the record does not carry it, report the cause as unknown.
- **A workflow change is only fully exercised by CI.** Extracting a `run:` block and executing it locally validates the script and nothing else, because `secrets: inherit`, `permissions:`, `needs:` wiring, and reusable-workflow inputs resolve only in a real run.
- **A review flags an instance, so fix the class.** When a reviewer cites one stale claim, one silent-narrowing pattern, or one mis-worded contract, sweep for its siblings before replying. Reviewers sample rather than enumerate.
Expand Down