From e1a6b205d7f4161e94cf2d476e2b571ee86809f1 Mon Sep 17 00:00:00 2001 From: William Valentin Date: Sun, 15 Feb 2026 18:16:54 -0800 Subject: [PATCH] docs(agents): codify branching, commits, and doc upkeep --- AGENTS.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index d71128f..1761fbc 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,7 +6,10 @@ - **Subagent model selection (MANDATORY):** You MUST use the right model tier for each subagent — `claude-haiku-4.5` for fast/simple/mechanical tasks, `claude-sonnet-4.5` for default/standard implementation work, and `claude-opus-4.6` for complex reasoning or architecture decisions. Never use the same model for all subagents. - **Minimize main agent context:** Always delegate tasks to subagents with the right model to execute each task more efficiently and keep the main agent context window usage minimum. The main agent should coordinate and synthesize, not perform detailed implementation work. - **Commit often:** `git commit` frequently — after each meaningful unit of work, not just at the end of a task. +- **Commit structure:** Prefer small, atomic commits that each represent one meaningful unit of work. Keep unrelated changes out of the same commit. When a change affects docs/diagrams/state, update and commit those alongside the code change (not later). +- **Branch + merge workflow:** Do work on a feature branch (`git switch -c feature/`). Keep branches rebased onto `main` (avoid merge commits). When finished: `git rebase main`, then fast-forward merge back to main: `git switch main && git merge --ff-only feature/`. - **Update state.json:** After every feature implementation, modification, or significant change, update `docs/plans/state.json` accordingly — add new phases/entries, update test counts, adjust the `overall_progress` section, and update the `feature_gap_scorecard` if the gap analysis is affected. Commit state.json alongside the feature change, not as a separate afterthought. +- **Keep docs + diagrams current:** When behavior, config keys, APIs, or architecture changes, update the relevant docs in the same change (README + `docs/`). If the change affects a documented flow, also update the corresponding Mermaid diagrams (e.g. `docs/architecture/AGENT_DIAGRAM.md`, `docs/api/PROTOCOL.md`) so they stay source-of-truth. ## Build, Lint, and Test Commands @@ -41,7 +44,7 @@ Flynn is a multi-channel AI assistant daemon. Messages flow: **Channel Adapter **ModelClient** (`src/models/types.ts`): `chat(request): Promise`. Providers: Anthropic, OpenAI, Gemini, Bedrock, Ollama, llama.cpp, GitHub Models, OpenRouter, Zhipu, xAI. Factory in `src/daemon/index.ts` (`createClientFromConfig()`). **ModelRouter** (`src/models/router.ts`) manages tiers (default/fast/complex/local) with fallback chains. -**ChannelAdapter** (`src/channels/types.ts`): `connect()`, `disconnect()`, `send()`, `onMessage()`. Adapters: Telegram, Discord, Slack, WhatsApp, WebChat. Registered in `ChannelRegistry`, each channel+sender pair gets its own session. +**ChannelAdapter** (`src/channels/types.ts`): `connect()`, `disconnect()`, `send()`, `onMessage()`. Adapters: Telegram, Discord, Slack, WhatsApp, Matrix, WebChat. Registered in `ChannelRegistry`, each channel+sender pair gets its own session. **Tool** (`src/tools/types.ts`): `{ name, description, inputSchema, execute(args): Promise }`. Three patterns: - Static: `export const fooTool: Tool = { ... }` (no deps)