feat(cmd): Add sequential agent workflow

[ATMackay]

Summary

This PR introduces the analyzer agent — a general-purpose agent for filesystem and CLI tasks (document analysis, code inspection, etc.) — alongside a major refactor that extracts a reusable workflow package and adds several new tools with unit tests. It also adds an ARCHITECTURE.md document.

Changes

New: workflow package (workflow/)

Extracts the session-creation + runner-event-loop pattern (previously inlined in the documentor command) into a reusable workflow.Workflow type. Both the documentor and the new analyzer agent now share this:

• workflow.go — New() constructs a workflow from an agent + session service + initial state; Start() creates a session, runs the agent loop, and logs token usage.
• runner.go — Defines the Runner interface wrapping google.golang.org/adk/runner.New: Analyzer agent (agents/analyzer/)

A new agent type focused on local filesystem operations and document analysis:

• analyzer.go — Configures the agent with its tool set (list_dir, read_local_file, write_file, edit_file, exec_command, search_files).
• prompt.go — System instructions with a structured workflow for exploring directories, reading files, handling binary documents (PDF, DOCX, archives), and writing output.
• config.go — Config struct with validation.New: cmd/analyze.go

Cobra command (agent run analyzer) with flags for --work-dir, --task, --output, --model, and --provider. Wires up the analyzer agent through the shared workflow package.New tools (tools/)

• fake_ctx_test.go — Lightweight tool.Context fake backed by an in-memory state map, enabling isolated tool tests without the full ADK runtime.
• tools_test.go — 12 test cases covering edit_file (replace once, not-found, ambiguous, replace-all), list_dir (basic, not-a-directory), read_local_file (snippet, missing file), and exec_command (success, non-zero exit, empty command).Refactored: state/ package

Moved tools/state.go → state/state.go as a standalone package with shared session state keys for both agents (StateWorkDir, StateOutputPath, StateRepoURL, etc.).Refactored: Documentor command (cmd/documentor.go)

Simplified significantly by delegating to the shared workflow package — the session/runner boilerplate is removed in favour of workflow.New() + workflow.Start().Refactored: Existing tools

• search.go → search_files.go (renamed for consistency).
• tools.go — Kind enum and GetTools()/GetToolByEnum() registry pattern replacing per-agent tool wiring.New: ARCHITECTURE.md

Comprehensive architecture documentation covering project structure, packages, agent workflows, tool system, LLM provider support, and session/state management.Other

• .gitignore — Updated with additional patterns.
• agents/documentor/prompt.go — Added UserMessage() helper.
• cmd/cmd.go — Wires up the new run → analyzer subcommand.
• cmd/constants.go — Adds userCLI constant.Stats