agim-cli 1.2.147 → 1.2.149

package/CHANGELOG.md

@@ -4,6 +4,164 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [1.2.149] - 2026-06-12
+
+### Fixed (ECC pack — folded-description parser bug)
+
+v1.2.148 的 bulk-import 脚本对 YAML 折叠语法（`description: >-\n  text...`）
+处理错误：把 `[ECC]` 前缀注入到 `>-` 那行而不是续行，导致 11 个 SKILL.md
+的 description 被解析成字面 `[ECC] >-` / `[ECC] >`：
+
+- 影响 skill：blueprint / customs-trade-compliance / energy-procurement /
+  frontend-a11y / inventory-demand-planning / logistics-exception-management /
+  production-scheduling / prompt-optimizer / quality-nonconformance /
+  returns-reverse-logistics / token-budget-advisor
+- 修复：从 ECC 源重新拷贝 + 智能注入（识别 YAML 块标量 marker，把 `[ECC] `
+  加到展开后的第一段文本，而非 marker 行）
+- 加固：`src/core/skills/loader.ts` `parseSkill` 加防御性 fallback——
+  description 解析后若是字面 `>-` / `|` / `>` / `|-`，自动用 fallback 文案
+  + `log.warn` 留审计（防未来同类静默失败）
+
+### Added (priority-bucket sort for system-prompt injection)
+
+`agim` 是 IM ↔ Agent 通用桥接框架，不应假设运营者的业务。但 builtin/ 加完
+229 ECC pack 后，**system prompt 前 32 个 skill 全是字母排序前段的 ECC 通用
+开发工具**，agim 自带框架 skill（`agim-*`）有 4 个能露脸，而非 ECC builtin
+（`github` / `image-generation` / `tmux` / `weather` 等）和精选 ECC 都被挤
+到字母序后段。
+
+#### 新策略（按设计意图）
+
+`src/core/skills/loader.ts` 新增 `rankSkillBucket(s)` 函数 + `ECC_TOP_PICKS`
+常量。`buildSkillsSummary` 改为"先按桶排序、桶内字母序"：
+
+| Bucket | 内容 |
+|---|---|
+| 0 | `agim-*` 框架 skill（4 个）|
+| 1 | 非 ECC builtin（8 个：github / image-generation / long-goal / my / skill-creator / summarize / tmux / weather）|
+| 2 | ECC 精选（20 个）— agent harness 工程 11 + 跨语言方法论 + 内容创作 9 |
+| 3 | 工作区运营者 skill（业务域）+ ECC 余下 210 |
+
+4 + 8 + 20 = 32 正好填满；bucket 3 全部靠 description match + 显式
+`mcp__imhub__read_skill('name')` 触发，不强占系统提示门面。
+
+#### ECC 精选清单（20 个）
+
+- **agent harness 工程（11）**：agentic-engineering / agent-eval /
+  agent-introspection-debugging / agent-harness-construction /
+  autonomous-agent-harness / autonomous-loops / continuous-learning-v2 /
+  verification-loop / prompt-optimizer / cost-aware-llm-pipeline /
+  context-budget
+- **跨语言方法论 + 内容（9）**：blueprint / coding-standards /
+  architecture-decision-records / code-tour / tdd-workflow /
+  security-review / benchmark / article-writing / content-engine
+
+#### 实测前 32 名（agim 默认）
+
+```
+ 1. agim-memory          2. agim-reminders      3. agim-self
+ 4. agim-skill-discovery 5. github              6. image-generation
+ 7. long-goal            8. my                  9. skill-creator
+10. summarize           11. tmux               12. weather
+13. agent-eval          14. agent-harness-construction
+15. agent-introspection-debugging              16. agentic-engineering
+17. architecture-decision-records              18. article-writing
+19. autonomous-agent-harness                   20. autonomous-loops
+21. benchmark           22. blueprint          23. code-tour
+24. coding-standards    25. content-engine     26. context-budget
+27. continuous-learning-v2                     28. cost-aware-llm-pipeline
+29. prompt-optimizer    30. security-review    31. tdd-workflow
+32. verification-loop
+```
+
+#### ECC 识别
+
+ECC pack 的 SKILL.md 各家 `origin:` 值不统一（`ECC` / `community` / `ECC
+direct-port adaptation` …），不能靠 frontmatter 严格等于 `ECC` 来判定。本
+轮以 description 的 `[ECC] ` 前缀作为可靠 marker（packaging 阶段统一打入），
+辅以 `origin:` 起始 `ECC` 的宽松匹配（前向兼容）。
+
+### Added (operator-decision re-import)
+
+- `content-engine` — 此前归入"ECC operator 工作流"剔除清单（v1.2.148），
+  本轮按设计决策复进 builtin/，跟 `article-writing` 一起作为内容创作类
+  ECC 精选。`ECC_NOTICE.md` 排除清单从 33 → 32，注明操作员决策。
+
+### Tests
+
+`src/core/skills/loader.test.ts` 新增 1 case 覆盖 `rankSkillBucket` 四桶分
+类 + `buildSkillsSummary` 输出顺序（agim-* < github/* < agent-eval (ECC 精
+选) < kotlin-* (ECC 余下) / fin-data-* (工作区)）。typecheck 双 pass 全绿；
+loader 套件 37/37 通过；build 7.5s。
+
+### 文件
+
+- `src/core/skills/loader.ts` — `SkillMeta.origin` 字段、`parseSkill` 抽
+  origin 并字面 block-scalar fallback、`ECC_TOP_PICKS` + `rankSkillBucket`
+  导出、`buildSkillsSummary` bucket-aware sort
+- `src/core/skills/loader.test.ts` — `rankSkillBucket` + sort 测试
+- `src/core/skills/builtin/<11 skill>/SKILL.md` — 折叠描述修复
+- `src/core/skills/builtin/content-engine/` — 复进 230 entry
+- `src/core/skills/builtin/ECC_NOTICE.md` — 233/32 + 复进说明
+
+## [1.2.148] - 2026-06-12
+
+### Added (built-in ECC skill pack — 229 skills)
+
+打包入了 [ECC](https://github.com/affaan-m/ECC) 项目 `skills/` 目录的精选子集：
+**229 个 skill**（占 ECC 全部 262 个的 87%），覆盖通用 dev 工作流、各语言
+patterns / testing / security / build-resolver、各主流框架（Django / Laravel /
+Spring Boot / Quarkus / NestJS / React / Vue / Nuxt 等）、agent harness 工程、
+verification 循环、cost-aware LLM 流水线等。MIT 许可，license 文件归档于
+`src/core/skills/builtin/ECC_LICENSE`。
+
+#### 标识
+
+- frontmatter `origin: ECC`
+- description 加 `[ECC]` 前缀（便于在 system prompt 一眼区分来源）
+
+#### env switch
+
+- `IMHUB_INCLUDE_ECC_SKILLS=off` （或 `0`/`false`/`no`/`disable`）→ loader 跳过
+  所有 `origin: ECC` 的 skill。默认 ON，保留新装 agim 用户的开箱即用体验。
+- 仅过滤 ECC pack；用户自己写 SKILL.md 时若复用 `origin: ECC` 字段是允许的
+  （但显式标记 ECC pack 的 description `[ECC]` 前缀已写死，不影响 user skill）。
+
+#### 33 项排除清单（不导入）
+
+- ECC 内部：`configure-ecc` / `ecc-guide` / `ecc-tools-cost-audit` / `workspace-surface-audit`
+- ECC operator 工作流：`brand-voice` / `customer-billing-ops` / `google-workspace-ops`
+  / `project-flow-ops` / `social-graph-ranker` / `social-publisher` /
+  `investor-materials` / `investor-outreach` / `carrier-relationship-management`
+  / `connections-optimizer` / `content-engine`
+- 视频生成：`manim-video` / `remotion-video-creation` / `blender-motion-state-inspection`
+- 预测市场（ito-*）：4 个
+- 家庭实验室（homelab-*）：5 个
+- 其他：`agent-architecture-audit` / `agent-payment-x402` / `agent-sort` /
+  `agentic-os` / `canary-watch` / `ck`
+
+#### 文件
+
+- 新增 `src/core/skills/builtin/<229 个目录>/` —— ECC skill 树原样拷贝
+  （部分含 scripts/references/templates 子目录），description 行加 `[ECC]` 前缀
+- 新增 `src/core/skills/builtin/ECC_LICENSE` —— MIT, © Affaan Mustafa
+- 新增 `src/core/skills/builtin/ECC_NOTICE.md` —— 归属说明 + 排除清单
+- `src/core/skills/loader.ts` —— `parseSkill` 加 IMHUB_INCLUDE_ECC_SKILLS 过滤
+- `src/core/skills/loader.test.ts` —— 新增 1 case 覆盖 env switch（默认 ON / off /
+  unrecognized 三态）
+
+#### 体积
+
+- builtin/ 从 12 个目录 → 241 个目录（含原 12 + 新 229）
+- 磁盘 ~80 KB → ~4.4 MB
+- 预估 npm tarball 增量约 +1.5 MB（gzip 后）
+
+#### 注意事项（agim user 视角）
+
+- system prompt 仍只列前 32 个 skill（`MAX_INJECTED_SKILLS=32`），不会爆 context
+- 其余 200+ 个仍可通过 `mcp__imhub__read_skill('name')` 主动调
+- 同名 workspace skill 会 shadow builtin（用户自定义优先）
+
 ## [1.2.147] - 2026-06-12
 
 ### Added (native harness — framework-level tool-call discipline + detector 双保险)

package/dist/core/skills/builtin/ECC_LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Affaan Mustafa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/core/skills/builtin/ECC_NOTICE.md

@@ -0,0 +1,28 @@
+# ECC skill pack — attribution
+
+Agim v1.2.148+ ships a curated subset of **230 skills** from the
+[ECC](https://github.com/affaan-m/ECC) project (commit cloned 2026-06-12),
+licensed under MIT. Each ECC-origin skill is identifiable by:
+
+- `origin: ECC` in its `SKILL.md` frontmatter
+- `[ECC]` prefix in its description (added at packaging time)
+
+Operators can disable the entire ECC skill pack via:
+
+```
+IMHUB_INCLUDE_ECC_SKILLS=off
+```
+
+Original license: `ECC_LICENSE` (MIT, © affaan-m).
+
+Excluded from the import (32 skills): ECC-internal tooling
+(configure-ecc, ecc-tools-*), ECC operator workflows (brand-voice,
+customer-billing-ops, google-workspace-ops, project-flow-ops, …),
+ito-* (4) prediction-market pack, homelab-* (5), video-generation
+(manim/remotion/blender), social-publisher, investor-materials/outreach.
+
+Re-imported after the initial cut (operator decision):
+- `content-engine` — cross-platform content systems (X / LinkedIn /
+  TikTok / YouTube / newsletter / repurposing). Originally excluded
+  with the operator-workflow group; promoted into the recommended-32
+  injection list as a general content-writing tool.

package/dist/core/skills/builtin/accessibility/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: accessibility
+description: [ECC] Design, implement, and audit inclusive digital products using WCAG 2.2 Level AA
+  standards. Use this skill to generate semantic ARIA for Web and accessibility traits for Web and Native platforms (iOS/Android).
+origin: ECC
+---
+
+# Accessibility (WCAG 2.2)
+
+This skill ensures that digital interfaces are Perceivable, Operable, Understandable, and Robust (POUR) for all users, including those using screen readers, switch controls, or keyboard navigation. It focuses on the technical implementation of WCAG 2.2 success criteria.
+
+## When to Use
+
+- Defining UI component specifications for Web, iOS, or Android.
+- Auditing existing code for accessibility barriers or compliance gaps.
+- Implementing new WCAG 2.2 standards like Target Size (Minimum) and Focus Appearance.
+- Mapping high-level design requirements to technical attributes (ARIA roles, traits, hints).
+
+## Core Concepts
+
+- **POUR Principles**: The foundation of WCAG (Perceivable, Operable, Understandable, Robust).
+- **Semantic Mapping**: Using native elements over generic containers to provide built-in accessibility.
+- **Accessibility Tree**: The representation of the UI that assistive technologies actually "read."
+- **Focus Management**: Controlling the order and visibility of the keyboard/screen reader cursor.
+- **Labeling & Hints**: Providing context through `aria-label`, `accessibilityLabel`, and `contentDescription`.
+
+## How It Works
+
+### Step 1: Identify the Component Role
+
+Determine the functional purpose (e.g., Is this a button, a link, or a tab?). Use the most semantic native element available before resorting to custom roles.
+
+### Step 2: Define Perceivable Attributes
+
+- Ensure text contrast meets **4.5:1** (normal) or **3:1** (large/UI).
+- Add text alternatives for non-text content (images, icons).
+- Implement responsive reflow (up to 400% zoom without loss of function).
+
+### Step 3: Implement Operable Controls
+
+- Ensure a minimum **24x24 CSS pixel** target size (WCAG 2.2 SC 2.5.8).
+- Verify all interactive elements are reachable via keyboard and have a visible focus indicator (SC 2.4.11).
+- Provide single-pointer alternatives for dragging movements.
+
+### Step 4: Ensure Understandable Logic
+
+- Use consistent navigation patterns.
+- Provide descriptive error messages and suggestions for correction (SC 3.3.3).
+- Implement "Redundant Entry" (SC 3.3.7) to prevent asking for the same data twice.
+
+### Step 5: Verify Robust Compatibility
+
+- Use correct `Name, Role, Value` patterns.
+- Implement `aria-live` or live regions for dynamic status updates.
+
+## Accessibility Architecture Diagram
+
+```mermaid
+flowchart TD
+  UI["UI Component"] --> Platform{Platform?}
+  Platform -->|Web| ARIA["WAI-ARIA + HTML5"]
+  Platform -->|iOS| SwiftUI["Accessibility Traits + Labels"]
+  Platform -->|Android| Compose["Semantics + ContentDesc"]
+
+  ARIA --> AT["Assistive Technology (Screen Readers, Switches)"]
+  SwiftUI --> AT
+  Compose --> AT
+```
+
+## Cross-Platform Mapping
+
+| Feature            | Web (HTML/ARIA)          | iOS (SwiftUI)                        | Android (Compose)                                           |
+| :----------------- | :----------------------- | :----------------------------------- | :---------------------------------------------------------- |
+| **Primary Label**  | `aria-label` / `<label>` | `.accessibilityLabel()`              | `contentDescription`                                        |
+| **Secondary Hint** | `aria-describedby`       | `.accessibilityHint()`               | `Modifier.semantics { stateDescription = ... }`             |
+| **Action Role**    | `role="button"`          | `.accessibilityAddTraits(.isButton)` | `Modifier.semantics { role = Role.Button }`                 |
+| **Live Updates**   | `aria-live="polite"`     | `.accessibilityLiveRegion(.polite)`  | `Modifier.semantics { liveRegion = LiveRegionMode.Polite }` |
+
+## Examples
+
+### Web: Accessible Search
+
+```html
+<form role="search">
+  <label for="search-input" class="sr-only">Search products</label>
+  <input type="search" id="search-input" placeholder="Search..." />
+  <button type="submit" aria-label="Submit Search">
+    <svg aria-hidden="true">...</svg>
+  </button>
+</form>
+```
+
+### iOS: Accessible Action Button
+
+```swift
+Button(action: deleteItem) {
+    Image(systemName: "trash")
+}
+.accessibilityLabel("Delete item")
+.accessibilityHint("Permanently removes this item from your list")
+.accessibilityAddTraits(.isButton)
+```
+
+### Android: Accessible Toggle
+
+```kotlin
+Switch(
+    checked = isEnabled,
+    onCheckedChange = { onToggle() },
+    modifier = Modifier.semantics {
+        contentDescription = "Enable notifications"
+    }
+)
+```
+
+## Anti-Patterns to Avoid
+
+- **Div-Buttons**: Using a `<div>` or `<span>` for a click event without adding a role and keyboard support.
+- **Color-Only Meaning**: Indicating an error or status _only_ with a color change (e.g., turning a border red).
+- **Uncontained Modal Focus**: Modals that don't trap focus, allowing keyboard users to navigate background content while the modal is open. Focus must be contained _and_ escapable via the `Escape` key or an explicit close button (WCAG SC 2.1.2).
+- **Redundant Alt Text**: Using "Image of..." or "Picture of..." in alt text (screen readers already announce the role "Image").
+
+## Best Practices Checklist
+
+- [ ] Interactive elements meet the **24x24px** (Web) or **44x44pt** (Native) target size.
+- [ ] Focus indicators are clearly visible and high-contrast.
+- [ ] Modals **contain focus** while open, and release it cleanly on close (`Escape` key or close button).
+- [ ] Dropdowns and menus restore focus to the trigger element on close.
+- [ ] Forms provide text-based error suggestions.
+- [ ] All icon-only buttons have a descriptive text label.
+- [ ] Content reflows properly when text is scaled.
+
+## References
+
+- [WCAG 2.2 Guidelines](https://www.w3.org/TR/WCAG22/)
+- [WAI-ARIA Authoring Practices](https://www.w3.org/TR/wai-aria-practices/)
+- [iOS Accessibility Programming Guide](https://developer.apple.com/documentation/accessibility)
+- [iOS Human Interface Guidelines - Accessibility](https://developer.apple.com/design/human-interface-guidelines/accessibility)
+- [Android Accessibility Developer Guide](https://developer.android.com/guide/topics/ui/accessibility)
+
+## Related Skills
+
+- `frontend-patterns`
+- `design-system`
+- `liquid-glass-design`
+- `swiftui-patterns`

package/dist/core/skills/builtin/agent-eval/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: agent-eval
+description: [ECC] Head-to-head comparison of coding agents (Claude Code, Aider, Codex, etc.) on custom tasks with pass rate, cost, time, and consistency metrics
+origin: ECC
+tools: Read, Write, Edit, Bash, Grep, Glob
+---
+
+# Agent Eval Skill
+
+A lightweight CLI tool for comparing coding agents head-to-head on reproducible tasks. Every "which coding agent is best?" comparison runs on vibes — this tool systematizes it.
+
+## When to Activate
+
+- Comparing coding agents (Claude Code, Aider, Codex, etc.) on your own codebase
+- Measuring agent performance before adopting a new tool or model
+- Running regression checks when an agent updates its model or tooling
+- Producing data-backed agent selection decisions for a team
+
+## Installation
+
+> **Note:** Install agent-eval from its repository after reviewing the source.
+
+## Core Concepts
+
+### YAML Task Definitions
+
+Define tasks declaratively. Each task specifies what to do, which files to touch, and how to judge success:
+
+```yaml
+name: add-retry-logic
+description: Add exponential backoff retry to the HTTP client
+repo: ./my-project
+files:
+  - src/http_client.py
+prompt: |
+  Add retry logic with exponential backoff to all HTTP requests.
+  Max 3 retries. Initial delay 1s, max delay 30s.
+judge:
+  - type: pytest
+    command: pytest tests/test_http_client.py -v
+  - type: grep
+    pattern: "exponential_backoff|retry"
+    files: src/http_client.py
+commit: "abc1234"  # pin to specific commit for reproducibility
+```
+
+### Git Worktree Isolation
+
+Each agent run gets its own git worktree — no Docker required. This provides reproducibility isolation so agents cannot interfere with each other or corrupt the base repo.
+
+### Metrics Collected
+
+| Metric | What It Measures |
+|--------|-----------------|
+| Pass rate | Did the agent produce code that passes the judge? |
+| Cost | API spend per task (when available) |
+| Time | Wall-clock seconds to completion |
+| Consistency | Pass rate across repeated runs (e.g., 3/3 = 100%) |
+
+## Workflow
+
+### 1. Define Tasks
+
+Create a `tasks/` directory with YAML files, one per task:
+
+```bash
+mkdir tasks
+# Write task definitions (see template above)
+```
+
+### 2. Run Agents
+
+Execute agents against your tasks:
+
+```bash
+agent-eval run --task tasks/add-retry-logic.yaml --agent claude-code --agent aider --runs 3
+```
+
+Each run:
+1. Creates a fresh git worktree from the specified commit
+2. Hands the prompt to the agent
+3. Runs the judge criteria
+4. Records pass/fail, cost, and time
+
+### 3. Compare Results
+
+Generate a comparison report:
+
+```bash
+agent-eval report --format table
+```
+
+```
+Task: add-retry-logic (3 runs each)
+┌──────────────┬───────────┬────────┬────────┬─────────────┐
+│ Agent        │ Pass Rate │ Cost   │ Time   │ Consistency │
+├──────────────┼───────────┼────────┼────────┼─────────────┤
+│ claude-code  │ 3/3       │ $0.12  │ 45s    │ 100%        │
+│ aider        │ 2/3       │ $0.08  │ 38s    │  67%        │
+└──────────────┴───────────┴────────┴────────┴─────────────┘
+```
+
+## Judge Types
+
+### Code-Based (deterministic)
+
+```yaml
+judge:
+  - type: pytest
+    command: pytest tests/ -v
+  - type: command
+    command: npm run build
+```
+
+### Pattern-Based
+
+```yaml
+judge:
+  - type: grep
+    pattern: "class.*Retry"
+    files: src/**/*.py
+```
+
+### Model-Based (LLM-as-judge)
+
+```yaml
+judge:
+  - type: llm
+    prompt: |
+      Does this implementation correctly handle exponential backoff?
+      Check for: max retries, increasing delays, jitter.
+```
+
+## Best Practices
+
+- **Start with 3-5 tasks** that represent your real workload, not toy examples
+- **Run at least 3 trials** per agent to capture variance — agents are non-deterministic
+- **Pin the commit** in your task YAML so results are reproducible across days/weeks
+- **Include at least one deterministic judge** (tests, build) per task — LLM judges add noise
+- **Track cost alongside pass rate** — a 95% agent at 10x the cost may not be the right choice
+- **Version your task definitions** — they are test fixtures, treat them as code
+
+## Links
+
+- Repository: [github.com/joaquinhuigomez/agent-eval](https://github.com/joaquinhuigomez/agent-eval)

package/dist/core/skills/builtin/agent-harness-construction/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: agent-harness-construction
+description: [ECC] Design and optimize AI agent action spaces, tool definitions, and observation formatting for higher completion rates.
+origin: ECC
+---
+
+# Agent Harness Construction
+
+Use this skill when you are improving how an agent plans, calls tools, recovers from errors, and converges on completion.
+
+## Core Model
+
+Agent output quality is constrained by:
+1. Action space quality
+2. Observation quality
+3. Recovery quality
+4. Context budget quality
+
+## Action Space Design
+
+1. Use stable, explicit tool names.
+2. Keep inputs schema-first and narrow.
+3. Return deterministic output shapes.
+4. Avoid catch-all tools unless isolation is impossible.
+
+## Granularity Rules
+
+- Use micro-tools for high-risk operations (deploy, migration, permissions).
+- Use medium tools for common edit/read/search loops.
+- Use macro-tools only when round-trip overhead is the dominant cost.
+
+## Observation Design
+
+Every tool response should include:
+- `status`: success|warning|error
+- `summary`: one-line result
+- `next_actions`: actionable follow-ups
+- `artifacts`: file paths / IDs
+
+## Error Recovery Contract
+
+For every error path, include:
+- root cause hint
+- safe retry instruction
+- explicit stop condition
+
+## Context Budgeting
+
+1. Keep system prompt minimal and invariant.
+2. Move large guidance into skills loaded on demand.
+3. Prefer references to files over inlining long documents.
+4. Compact at phase boundaries, not arbitrary token thresholds.
+
+## Architecture Pattern Guidance
+
+- ReAct: best for exploratory tasks with uncertain path.
+- Function-calling: best for structured deterministic flows.
+- Hybrid (recommended): ReAct planning + typed tool execution.
+
+## Benchmarking
+
+Track:
+- completion rate
+- retries per task
+- pass@1 and pass@3
+- cost per successful task
+
+## Anti-Patterns
+
+- Too many tools with overlapping semantics.
+- Opaque tool output with no recovery hints.
+- Error-only output without next steps.
+- Context overloading with irrelevant references.