agent design principles

principle 1: single responsibility
  each agent should have ONE primary expertise area.
  dont create "general purpose" agents.

  good: python-cli-llm-dev focuses on cli tools with llm integration
  bad:  python-expert does "everything python"

principle 2: clear boundaries
  agents should know what they do AND what they dont do.

  example:
    coder agent:
      does: implementation, debugging, testing
      doesnt: documentation (thats technical-writer)

principle 3: composability
  agents should work well together.
  users might use multiple agents in one session.

  workflow:
    1. coder implements feature
    2. technical-writer documents it
    3. researcher validates approach

principle 4: context awareness
  use <trender> tags to provide dynamic, relevant context.

  examples:
    - git status for coder agent
    - documentation files for writer agent
    - package.json for node specialist

principle 5: practical examples
  every capability should have concrete examples.
  show, dont just tell.

  weak:   "i can help with testing"
  strong: [provides actual test execution examples]

principle 6: terminal-first
  all output must work in plain text terminals.
  no markdown rendering assumptions.

  formatting rules:
    [ok] simple labels with colons
    [ok] plain checkboxes [x] [ ]
    [ok] status tags [ok] [warn] [error]
    [ok] blank lines for readability

