Follow up Goose upstream updates: goose review checks surface, retired .gooseignore, custom agents (.agents/agents/*.md)

[dyoshikawa]

Summary

Goose has three surfaces rulesync has not followed: the goose review checks surface (.agents/checks/*.md, shipped v1.35.0, 2026-05-22), the first-class Markdown custom-agent format (.agents/agents/*.md, shipped v1.34.0, 2026-05-13) that rulesync's recipe-YAML subagent mapping does not reach, and .gooseignore, which upstream has retired but rulesync still generates.

Note on sources: block/goose now redirects to aaif-goose/goose (gh api repos/block/goose → full_name: aaif-goose/goose), and the canonical docs host is now https://goose-docs.ai (GOOSE_DOCS_ROOT default in documentation/docs/guides/config-files.md); https://block.github.io/goose/docs/ still serves the same content.

Recent Releases

• v1.44.0 (2026-07-23) — release — Stop hook gains working_dir; hooks docs formalize the deny contract / matcher regex / tool_input keys; stale .gooseignore references removed from docs (#10359); goose review security fix (GHSA-r5pp-p5r8-466r).
• v1.43.0 (2026-07-14) — release — custom agents guide docs (#9293 / #9947); streamable HTTP deeplink generator.
• v1.41.0 (2026-07-03) — global hints ~/.agents/AGENTS.md (already followed, Follow up Goose upstream updates: global hints from ~/.agents/AGENTS.md (v1.41.0) #2207).
• v1.40.0 (2026-07-02) / v1.39.0 (2026-06-25) — open-plugin MCP .agents/plugins/<name>/.mcp.json (already followed, Follow up Goose upstream updates: project-scoped MCP via open plugins (.agents/plugins/<name>/.mcp.json, v1.39.0) #2078).
• v1.38.0 (2026-06-17) — plugins install to ~/.agents/plugins (#9088).
• v1.35.0 (2026-05-22) — goose review local code-review command first released (PR #9114, merged 2026-05-18).
• v1.34.0 (2026-05-13) — Agents CRUD / filesystem agent discovery (PR #9084, merged 2026-05-11).

Gaps

1. checks — goose review with .agents/checks/*.md is unsupported

• Upstream: goose review runs per-check review subagents discovered from Markdown check files. Source of truth is crates/goose/src/checks/mod.rs, whose module doc reads "Discovery and parsing for review checks (.agents/checks/*.md and **/.agents/REVIEW.md)". PR #9114 (merged 2026-05-18), first released in v1.35.0 (2026-05-22).
  • Project discovery (discover_with_globals): <repo>/.agents/checks/*.md (strict — name must equal the file stem), nested <scope>/.agents/checks/*.md for touched dirs, plus <repo>/.agents/REVIEW.md and nested REVIEW.md synthesized into virtual repo-rules[:scope] checks. README.md is skipped.
  • Global discovery (global_checks_dirs()): ~/.config/goose/checks/ then ~/.config/agents/checks/ (lenient parsing).
  • Frontmatter (CheckFrontmatter): name, description, model, turn-limit, tools, severity-default. The source comments state that tools and severity-default exist "for parity with Amp's" fields and that .agents/checks/*.md is explicitly the shared cross-tool location.
• rulesync: unsupported. pnpm run dev generate --targets goose --features "*" --global --dry-run prints Target 'goose' does not support the feature 'checks'. Skipping. Only src/features/checks/amp-check.ts and src/features/checks/hermesagent-check.ts exist; there is no goose-check.ts.
• Note: there is no docs page for goose review / checks yet — the merged PR and the crate source are the primary sources.

2. ignore — .gooseignore has been retired upstream, rulesync still emits it

• Upstream: .gooseignore no longer exists in Goose.
  • The docs page documentation/docs/guides/using-gooseignore.md and every reference to it were deleted by PR #10359 ("docs: remove stale gooseignore references", merged 2026-07-15, shipped v1.44.0 on 2026-07-23).
  • That PR closes issue #10343 ("Has the .gooseignore feature been removed?"), where the maintainer confirms on 2026-07-09: "yeah it was removed some time ago in favour of other ignore things like gitignore etc".
  • The permissions doc diff in that PR removed the ".gooseignore files restrict which files and directories goose can access" bullet, leaving tool permissions as the only file-access control.
  • Confirmed absent from the current tree: gh api repos/aaif-goose/goose/git/trees/main?recursive=1 has no gooseignore path, and a code search for gooseignore returns nothing.
  • The replacement guidance is .gitignore plus tool permissions; there is no new Goose-specific ignore file.
• rulesync: project, writing .gooseignore at the project root (src/features/ignore/goose-ignore.ts, GOOSE_IGNORE_FILE_NAME in src/constants/goose-paths.ts). The dry-run confirms [DRY RUN] Would write: /workspace/.gooseignore. The class doc still describes "Default protection (when no .gooseignore)" and "Global patterns first, then local patterns", which no longer matches upstream. Follow up Goose upstream updates: hooks emit unsupported SubagentStart/SubagentStop events (and global .gooseignore) #2149 previously added global .gooseignore handling that is now moot.

3. subagents — custom agents (.agents/agents/*.md) are not emitted; rulesync writes inert sub-recipes

• Upstream: Goose has a first-class Markdown custom-agent surface. Docs: custom agents guide, added by PR #9293 (merged 2026-06-22, in v1.39.0+). Filesystem discovery landed with PR #9084 ("Agents crud", merged 2026-05-11, v1.34.0 on 2026-05-13), implemented in crates/goose/src/sources.rs (agent_base_dir) and crates/goose/src/agents/platform_extensions/summon.rs (discover_filesystem_sources).
  • Project dirs: <project>/.agents/agents/, <project>/.goose/agents/, <project>/.claude/agents/. Global dirs: ~/.agents/agents/, ~/.goose/agents/, ~/.config/goose/agents/, ~/.claude/agents/. Docs recommend .agents/agents/ (project) and ~/.agents/agents/ (global); the rest are compatibility paths.
  • Format: Markdown with YAML frontmatter — name (required), description (optional), model (optional); the body is the agent instructions. Agents are invocable via @name, "delegate to <name>", or loaded into the current conversation.
• rulesync: project + global, but it maps a subagent to a recipe YAML under .goose/recipes/subagents/<name>.yaml / ~/.config/goose/recipes/subagents/<name>.yaml (src/features/subagents/goose-subagent.ts, src/constants/goose-paths.ts). Per the constant's own comment these are sub-recipes intended to be referenced from a parent recipe via a relative path; rulesync emits no parent recipe, and discover_filesystem_sources scans .goose/recipes / .agents/recipes (not the subagents/ subdirectory), so the generated files are not reachable as agents or sources on their own. No rulesync target writes .goose/agents/ or ~/.config/goose/agents/; agentsmd-subagent.ts writes .agents/subagents/, a different directory from .agents/agents/.

4. skills — goose-specific global skills dir not covered (low priority, needs a decision)

• Upstream: crates/goose/src/skills/mod.rs discovery roots are project <wd>/.agents/skills, <wd>/.goose/skills, <wd>/.claude/skills; global ~/.agents/skills, Paths::config_dir()/skills (i.e. ~/.config/goose/skills/), ~/.claude/skills, ~/.config/agents/skills. Docs: using skills.
• rulesync: project only. GOOSE_SKILLS_DIR_PATH = .goose/skills (src/constants/goose-paths.ts), and the global dry-run prints Target 'goose' supports the feature 'skills' only in project scope. Re-run without '--global'. Skipping. The constant's comment justifies project-only on the grounds that the recommended portable global location ~/.agents/skills/ is already served by the agentsskills target — which is reasonable, but the goose-specific ~/.config/goose/skills/ is not covered by agentsskills (that target owns .agents/skills).

Proposed Follow-up

1. Add a GooseCheck adapter emitting .agents/checks/<name>.md (project) and ~/.config/goose/checks/<name>.md (global), registered in checks-processor.ts. The frontmatter is a superset of Amp's (name, description, severity-default, tools) plus model and turn-limit, so AmpCheck is the closest template. name must match the file stem for project-scope checks or Goose errors out. REVIEW.md is auto-derived by Goose and needs no rulesync surface.
2. Drop ignore from the goose target's getToolTargets (the matrix cell becomes blank), remove GooseIgnore / GOOSE_IGNORE_FILE_NAME, and drop the .gooseignore gitignore entry derived from getSettablePaths. If a deprecation path is preferred, gate it behind a warning first — but generating a file Goose no longer reads gives users a false sense of protection over secrets, so removal is the safer end state.
3. Switch (or add) the goose subagent surface to the custom-agent Markdown format — .goose/agents/<name>.md (project) and ~/.config/goose/agents/<name>.md (global), keeping the goose-specific compatibility paths so it does not collide with a future shared .agents/agents/ target. Frontmatter maps directly from rulesync subagents: name, description, optional model.
4. Decide whether --global --targets goose should be self-contained for skills; if so, add ~/.config/goose/skills/<name>/SKILL.md as the global settable path. Flagged for a decision rather than asserted as a required change.

Checked and NOT a gap

• rules — .goosehints (project + ~/.config/goose/.goosehints global), AGENTS.md, nested hints, and ~/.agents/AGENTS.md global hints (v1.41.0) are all already followed (Follow up Goose upstream updates: AGENTS.md context file and global .gooseignore #1691, Follow up Goose upstream updates: global hints from ~/.agents/AGENTS.md (v1.41.0) #2207).
• hooks — upstream events (SessionStart, SessionEnd, Stop, UserPromptSubmit, PreToolUse, PostToolUse, PostToolUseFailure, BeforeReadFile, AfterFileEdit, BeforeShellExecution, AfterShellExecution) match GOOSE_HOOK_EVENTS (src/types/hooks.ts) exactly, including the SubagentStart / SubagentStop exclusion (Follow up Goose upstream updates: hooks emit unsupported SubagentStart/SubagentStop events (and global .gooseignore) #2149). v1.44.0's Stop-hook working_dir is a runtime payload field, not a config surface.
• plugin manifest — plugin.json is not required for discovery: crates/goose/src/plugins/discovery.rs discover_enabled_plugins enumerates <project>/.agents/plugins/* and ~/.agents/plugins/* directly; the manifest is only used by goose plugin install. rulesync's manifest-less .agents/plugins/rulesync/ tree is fine.
• mcp — global config.yaml extensions: (stdio / streamable_http / sse / builtin, uri / headers / envs / timeout) and project open-plugin .agents/plugins/rulesync/.mcp.json are both handled. available_tools, bundled and display_name are dropped on import but have no canonical rulesync equivalent.
• commands — recipes at .goose/recipes/ (project) and ~/.config/goose/recipes/ (global) are still the discovery paths. The slash_commands: config.yaml key requires an absolute recipe_path per command and is unchanged; plugin commands/ dirs are install-detection markers only.
• permissions — still global-only upstream: crates/goose/src/config/permission.rs builds PermissionManager::new(Paths::config_dir()) → ~/.config/goose/permission.yaml. No project scope added.
• disabledPlugins / project settings.json — an enable/disable switch for plugins, not a rulesync feature surface.

Open questions / unconfirmed

• The exact Goose version in which the .gooseignore code was removed. The docs removal is v1.44.0 and the maintainer says "removed some time ago", but no single removal commit surfaced via commit search — it appears to have been dropped inside a larger developer-extension refactor. Its absence from the current tree and the maintainer's statement are solid; the version number is not.

References

• https://github.com/aaif-goose/goose/releases/tag/v1.44.0 — the release that removed the .gooseignore docs and hardened goose review (gaps 1–2).
• feat(cli): add goose review local code review command aaif-goose/goose#9114 — the goose review / checks PR, first released in v1.35.0 (gap 1).
• docs: remove stale gooseignore references aaif-goose/goose#10359 — the docs PR that deleted every .gooseignore reference (gap 2).
• Has the .gooseignore feature been removed? aaif-goose/goose#10343 — maintainer confirmation that .gooseignore was removed (gap 2).
• Agents crud aaif-goose/goose#9084 — "Agents crud", the filesystem agent discovery PR (gap 3).
• docs: custom agents aaif-goose/goose#9293 — the custom agents docs PR (gap 3).
• https://block.github.io/goose/docs/guides/context-engineering/custom-agents/ — the custom-agent file format and discovery dirs (gap 3).
• https://block.github.io/goose/docs/guides/context-engineering/using-skills/ — skills discovery roots including ~/.config/goose/skills/ (gap 4).

[dyoshikawa]

Gaps 2 and 3 are fixed by #2460 (merged). Gaps 1 and 4 stay open here.

Fixed

• Gap 3 (inert subagents). GooseSubagent now emits Goose custom agents — Markdown with name/description/model frontmatter — to .goose/agents/ (project) and ~/.config/goose/agents/ (global), the goose-specific discovery dirs, so a future shared .agents/agents/ target cannot collide. The old sub-recipe YAML under .goose/recipes/subagents/ (never scanned by Goose's agent discovery) is no longer generated; stale outputs stay gitignored. Recipe-only section keys (version, title, instructions, …) are stripped rather than leaked into the new frontmatter — note the old goose.instructions body override is gone by design, since the custom-agent body is the instructions.
• Gap 2 (.gooseignore). The goose ignore target is removed (upstream retired the file; generating it gave a false sense of protection). Stale outputs stay gitignored; the docs record the replacement guidance (.gitignore + tool permissions).

Still open

• Gap 1 — goose review checks adapter. A new Tool × Feature cell (GooseCheck emitting .agents/checks/<name>.md project + ~/.config/goose/checks/<name>.md global, AmpCheck as the template plus model/turn-limit, stem-must-match-name constraint). Well-specified above and ready to implement as its own PR.
• Gap 4 — goose-specific global skills dir (~/.config/goose/skills/). Still a design decision, as the issue frames it: whether --global --targets goose should be self-contained for skills or keep relying on the agentsskills target's ~/.agents/skills/.

[dyoshikawa]

Re-validation pass (2026-07-29), two new facts worth recording on the open gaps:

Gap 1 (Goose checks adapter) — the project-scope path collides with Amp's. Goose's project checks directory .agents/checks/*.md is byte-identical to what the existing amp checks target already writes (AMP_CHECKS_PROJECT_DIR = .agents/checks, src/constants/amp-paths.ts:5,8). Goose's own source states its tools and severity-default fields exist for parity with Amp's — .agents/checks/ is a deliberate shared cross-tool location, so a user who enables the amp checks target is already feeding goose review. Globals do not collide (Amp: ~/.config/amp/checks, Goose: ~/.config/goose/checks then ~/.config/agents/checks, loaded leniently per crates/goose/src/checks/mod.rs). This changes the shape of the decision: either allow two rulesync targets to own the same output path, or make a goose checks target global-only (the genuinely uncovered surface) and delegate project scope to amp. Also verified from the Rust source: frontmatter = name/description/model/turn-limit/tools/severity-default, name defaults to the file stem, and the name-matches-filename constraint is enforced for repo-local checks only; REVIEW.md is synthesized into virtual checks automatically, so it needs no rulesync surface.

Gap 4 (~/.config/goose/skills/) — recommend closing as a non-gap. crates/goose/src/skills/mod.rs:38 comments ~/.agents/skills as the "Canonical writable location for global user skills"; ~/.config/goose/skills is one of four read-only global fallbacks. rulesync's existing delegation of Goose global skills to the agentsskills target (~/.agents/skills, rationale at src/constants/goose-paths.ts:27-35) is therefore endorsed by upstream's own source; adding the fallback dir would duplicate output into a non-canonical location.

Leaving the issue open for the gap 1 ownership decision.

[dyoshikawa]

Upstream update (re-check on 2026-07-30)

Window: v1.33.1 (2026-04-29) → v1.45.0 (2026-07-29, newest — published after this issue's last re-validation).

Status of the gaps recorded here

• Gap 1 (goose review checks): still valid — crates/goose/src/checks/mod.rs on current main still discovers .agents/checks/*.md + **/.agents/REVIEW.md with the same frontmatter set, and the dry-run still prints Target 'goose' does not support the feature 'checks'. Skipping. New fact: crates/goose/src/sources.rs now surfaces .agents/checks/*.md checks as delegatable sources listed alongside agents and skills — the surface is broader than "inputs to goose review", strengthening the case for a GooseCheck adapter (the Amp path-collision ownership decision is unchanged).
• Gap 2 (retired .gooseignore): fixed by fix(goose): emit subagents as the custom agents Goose reads, retire the removed .gooseignore #2460 — no goose-ignore.ts exists and neither dry-run emits .gooseignore.
• Gap 3 (custom agents): fixed by fix(goose): emit subagents as the custom agents Goose reads, retire the removed .gooseignore #2460 — dry-runs write .goose/agents/*.md and ~/.config/goose/agents/*.md; upstream frontmatter is still exactly name/description/model, so the mapping is complete.
• Gap 4 (~/.config/goose/skills/): confirmed non-gap — current using-skills.md lists only ~/.agents/skills/, .agents/skills/, and plugin skills, labeling the rest backward compatibility.

Additional or changed gaps

1. hooks — a "*" matcher silently kills the whole Goose hook rule. Goose compiles matcher with Regex::new and on error logs "Invalid hook matcher regex; skipping rule" and drops the entire rule (crates/goose/src/hooks/mod.rs); a bare "*" is an invalid regex, and the v1.44.0 docs pass (PR #10467, v1.44.0, 2026-07-23) now states outright that "*" is "silently skipped". rulesync emits the canonical matcher verbatim (verified: a canonical matcher: "*" lands in the generated hooks.json as-is → a hook that never runs). Since "*" is valid for Claude Code, a shared canonical hooks file silently produces dead hooks on Goose. rulesync already normalizes this idiom for four targets (amp-plugin-generator.ts, opencode-style-generator.ts, pi-extension-generator.ts, vibe-hooks.ts); apply the same "treat "*" as no matcher" rule in goose-hooks.ts.
2. mcp — global generate deletes the user's non-rulesync extensions from config.yaml. GooseMcp.fromRulesyncMcp merges with { ...config, extensions: convertToGooseFormat(...) } (src/features/mcp/goose-mcp.ts), replacing the entire extensions: map. Verified: starting from a config.yaml holding the standard developer and memory builtins plus a rulesync-managed server, a global MCP generate produced a file containing only the rulesync server — both builtins gone, which breaks the agent (developer provides the shell/text-editor tools; builtins documented in documentation/docs/guides/config-files.md).
3. mcp — import rewrites builtin/platform extensions as broken stdio entries. Upstream documents six extension types (builtin, platform, stdio, streamable_http, frontend, inline_python, plus legacy sse); convertFromGooseFormat maps only the three MCP-ish ones and drops the type otherwise, and resolveGooseType defaults a type-less entry to stdio. Verified round-trip: developer: {type: builtin, bundled: true, timeout: 300} → import → regenerate → {name: developer, type: stdio, timeout: 300} with no cmd — a working builtin turned into an unstartable stdio extension. This goes beyond the earlier "bundled/display_name dropped" note: the type itself is destroyed.

Gaps 2 and 3 share one root cause — config.yaml is co-owned but rulesync treats it as rulesync-owned. A single follow-up ("own only rulesync-managed extension names via the shared-config gateway ownedKeys pattern; skip or round-trip non-MCP extension types; never synthesize type: stdio without cmd/uri") resolves both. Minor note to fold in: the global merge round-trips config.yaml through js-yaml dump(), losing the user's comments/formatting on every generate.

Verified non-gaps in the window

v1.45.0 introduces no new config surface (built-in skill disabling is a runtime switch). Rules, commands/recipes, hook events (eleven, matching GOOSE_HOOK_EVENTS), and global-only permissions (permission.yaml matches the Rust PermissionConfig shape) are all current. The new project-scope settings.json disabledPlugins key is an enable/disable switch, not a rulesync surface; the manifest-less .agents/plugins/rulesync/ tree remains discoverable.

References

• https://github.com/aaif-goose/goose/releases/tag/v1.44.0 and docs: document hook deny contract, matcher regex, tool_input keys, and provider config aaif-goose/goose#10467 — the docs formalization that "*" matchers are silently skipped (new gap 1).
• https://github.com/aaif-goose/goose/releases — release timeline v1.33.1 → v1.45.0.
• documentation/docs/guides/config-files.md in the goose repo — extension types and builtin extensions (new gaps 2–3).