feat: ARCHITECTURE.md for agents to quick reference

[tlongwell-block]

Add ARCHITECTURE.md

Documents core abstractions and where to find things in the codebase. Intended to help agents (and humans) orient themselves before making changes.

[tlongwell-block]

/goose is this accurate and worthwhile? As concise as possible while being useful? Worth the tokens to enable llm agents to find what they need faster? Or just hard to maintain cruft that will quickly go out of date and cause confusion? Keep in mind, agents automatically read AGENTS.md

[github-actions[bot]]

Summary: Adds ARCHITECTURE.md documenting core abstractions and file locations. All paths and claims are accurate. This provides value by separating conceptual understanding (ARCHITECTURE.md) from operational commands (AGENTS.md), letting agents read it selectively.

✅ Highlights

• Accuracy: Verified every file path, function reference, and claim against the codebase:

  • All 21 "Where Things Live" paths exist
  • "20+ implementations" is accurate (found 24 impl Provider)
  • Session ID format YYYYMMDD_N verified (session_manager.rs:862-871)
  • All 7 extension types match ExtensionConfig enum in extension.rs
  • temporal-service/ removal is correct (directory doesn't exist)

• Good separation of concerns: AGENTS.md (auto-read) stays lean with commands and rules. ARCHITECTURE.md provides deeper context that agents can read selectively, avoiding token cost for simple tasks.

• Scannable format: Tables with "To work on..." structure help agents quickly find the right files without reading prose.

• Key entry points section: Directly links concepts to specific functions with file locations—exactly what an agent needs to start tracing code.

🟢 Suggestions

1. ARCHITECTURE.md:58 - The "20+ implementations" could be "24 implementations" for precision, but the vague number is more maintainable as providers change.

2. Maintenance note - Consider adding a reminder at the top of ARCHITECTURE.md (or in AGENTS.md reference) to update it when adding/modifying core abstractions. This addresses the staleness risk inherent in documentation.

Assessment of Reviewer Questions:

• Accurate? Yes, thoroughly verified.
• Concise? Yes, uses tables and terse descriptions.
• Worth the tokens? Yes—agents read AGENTS.md automatically but can skip ARCHITECTURE.md for simple tasks. When they do need architectural context, having it pre-summarized saves exploration time.
• Will it go out of date? Moderate risk. File paths are stable, but function names/descriptions could drift. The current AGENTS.md reference saying "Read it first, update it when adding or changing abstractions" addresses this.

---

Review generated by goose

[katzdave]

Does this meaningfully reduce context usage if you were to ask to say summarize how recipes or extensions work (vs discovering on its own)?

Otherwise I'd say feels like a place where the paths will just drift.

[tlongwell-block]

Does this meaningfully reduce context usage if you were to ask to say summarize how recipes or extensions work (vs discovering on its own)?

Otherwise I'd say feels like a place where the paths will just drift.

Yes...

... when goose actually follows AGENTS.md and reads ARCHITECTURE.md first. Which... is not often unless prompted. That alone may make this not worthwhile.

---

Without ARCHITECTURE.md:

🐚 ~/Development/goose-auto-ci pr_reviewer_arch ~/Development/goose/target/release/goose-tui --cli

goose CLI mode
provider: databricks
model:    goose-claude-4-5-opus
session:  20251218_402

Type your message and press Enter. Use /help for commands.

✓ Project context loaded

( O)> Explain how recipes work in goose
                    
I'll explore the codebase to understand how recipes work in goose. Let me look at the relevant files.

┌─ tool: code_execution__read_module
│  module_path: developer
└─
✓ code_execution__read_module completed

... redacted ...

context: [█████░░░░░░░░░░░░░░░] 26% (53259/200000)
( O)> 

With ARCHITECTURE.md:

🐚 ~/Development/goose-minimal-subrecipes architecture_for_agents ~/Development/goose/target/release/goose-tui --cli

goose CLI mode
provider: databricks
model:    goose-claude-4-5-opus
session:  20251218_404

Type your message and press Enter. Use /help for commands.

✓ Project context loaded

( O)> Explain how recipes work in goose. Read the architecture file first
                    
┌─ tool: code_execution__execute_code
│  code: import { text_editor } from "developer"; text_editor({ command: "view", path: "ARCHITECTURE.md" }) 
└─
✓ code_execution__execute_code completed

... redacted ...

context: [███░░░░░░░░░░░░░░░░░] 19% (39763/200000)
( O)> 

[katzdave]

Ehh if we have to prompt it explicitly probably not all that useful then?

If you got that boost from just the ref in agents.md I'd say send it.

[tlongwell-block]

Closing this for now. Will experiment more later. Maybe with just a minimal version of "core abstractions" in AGENTS.md once we have automated documentation validation in CI