feat: public launch — MIT license, brand block, governance, and multi-agent workspaces by feliperun · Pull Request #4 · feliperun/expert-agent

feliperun · 2026-04-17T21:03:38Z

Summary

Bundles six commits that together bring expert-agent from its previous
dev-y state to a shape suitable for a public v0.1.x alpha: proper
multi-agent ergonomics, correct defaults, a visible brand, a permissive
license, and all of the governance scaffolding (contrib docs, templates,
security policy, companion guide for private downstream repos).

Every commit is standalone and passes the full suite (ruff, mypy,
pytest — 88 tests).

Commits (bottom → top of the branch)

1. `feat(cli): multi-agent workspaces with @alias, expert.toml, and expert use`

Introduces Workspace.discover(), the @alias argv rewriter, and the
expert agents / expert use / expert which commands. Agent-aware
commands accept --agent/-a and resolve via a single precedence chain
(--schema → --agent/@alias → EXPERT_AGENT env → pinned state
file → expert.toml [defaults] → single-agent short-circuit).

2. `fix: ship correct defaults for count-tokens, version, and testkit`

Three tiny independent fixes worth calling out:

__version__ now comes from importlib.metadata (no more hardcoded
0.1.0 drifting from pyproject.toml).
expert count-tokens default model moves from the deprecated
gemini-2.0-flash-exp to gemini-2.5-flash. The backend smoke-test
default (backend/app/llm/gemini_ai_studio.py:DEFAULT_MODEL) follows
suit. Same change inside the Robot Framework fixture.
ExpertLibrary.run_cli(expect_rc=...) is typed int | None = 0 so
Robot's dynamic-argument converter accepts ${None} from suite files
without trying to coerce None into int.

3. `chore: use synthetic agent names in examples and fixtures`

Replaces the descriptive-but-leaky ecg-expert / ECG_* with neutral
my-expert / MY_EXPERT_* throughout docstrings, test fixtures, and
public-facing docs. No behavioural change.

4. `chore(license): relicense under MIT`

Apache-2.0 → MIT. Simpler, more permissive, better match for the
target audience. Both LICENSE and pyproject.toml updated; classifier
follows.

5. `feat(cli): brand block + refined glyphs`

New cli/expert/brand.py: shared ANSI-shadow wordmark + tagline,
optionally with installed version + license line. Reused by
expert --version and exposed as a hidden expert brand command.
cli/expert/ui.py: emoji-free single-glyph prefixes
(✓ / ✗ / ⚠ / >) plus three new helpers (print_hint,
print_step, print_kv) for consistent spacing across commands.
New cli/tests/test_brand.py + updated test_init.py for the new
output formatting.

6. `docs: add governance, PR/issue templates, and private-agent-repo guide`

Governance: AGENTS.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md,
SECURITY.md.
GitHub templates: ISSUE_TEMPLATE/bug_report.yml,
feature_request.yml, config.yml, PULL_REQUEST_TEMPLATE.md.
New docs/PRIVATE_AGENT_REPO.md: step-by-step playbook for teams
spinning up a private repo that consumes expert-agent as a library
(layout, expert.toml conventions, CI wiring, secret hygiene).
README.md rewrite to lead with the tagline, surface multi-agent
workspaces, and link to the new guide.

Test plan

ruff check . — clean
mypy backend cli — 46 files, no issues
pytest — 88/88 green in ~2.6s
expert --version renders the brand block (locally verified)
expert count-tokens against a real schema with the new default
model succeeds (verified against a downstream agent deployment)
Robot Framework suites 01_validate / 03_update (CI to confirm)

Notes for reviewers

No secrets, no tenant-specific details, no customer data in the diff.
docs/PRIVATE_AGENT_REPO.md is written for downstream consumers
(private repos that depend on this framework). It's intentionally
generic — see §6 of that doc for the naming hygiene this PR also
enforces upstream.
The license switch is a one-way door for accepted contributions so
far, but the contributor base is first-party only, so the migration
is low-risk. Future contributions will land under MIT.

Made with Cursor

@derm

…expert use` Single-agent repos keep their existing ergonomics; multi-agent repos get a first-class experience via three equivalent targeting syntaxes and a shared resolver so every command picks up precedence rules automatically. ## New surface - `expert agents` — list every agent (TOML-declared + auto-discovered siblings) - `expert use <name>` — pin an agent in `.expert/state.json` for this workspace - `expert which [--agent ...]` — preview what a bare command would resolve to - `@alias` positional shortcut: `expert @derm ask "..."` → same as `expert ask --agent derm "..."` - `--agent/-a <name>` flag on `ask`, `validate`, `count-tokens`, `sync`, `test`, `sessions list|show|delete`, plus `which` for previewing resolution - `expert.toml` at the workspace root with `[defaults]` + `[agents.<name>]` sections (schema path, endpoint, api_key_env, description) ## Resolution precedence (first match wins) 1. `--schema <path>` short-circuits to that file (preserves legacy behaviour) 2. `--agent <name>` / `@alias` (explicit selector) 3. `EXPERT_AGENT` env var 4. `.expert/state.json` (set by `expert use`) 5. `[defaults] agent = "..."` in `expert.toml` 6. Exactly-one-agent short-circuit Failing to disambiguate raises `AmbiguousAgentError` with a helpful message listing every candidate and the three ways to pick one. ## Architecture - `cli/expert/workspace.py`: `Workspace.discover()`, `AgentContext`, `AgentInfo`, `AmbiguousAgentError`. Walks up for `expert.toml` or `.expert/state.json`; falls back to sibling-schema discovery rooted at cwd. - `cli/expert/context.py`: single `resolve()` helper called by every command, so changing precedence rules in the future is a one-file edit. - `cli/expert/main.py`: argv rewriter that expands `@alias` before Typer parses, with an allow-list of agent-aware subcommands so nonsense like `expert @foo use bar` is left alone for Typer's error renderer. ## Docs & CI - Reusable workflow (`.github/workflows/expert-e2e.yml`) gains an `agent:` input so monorepos can run `expert test --agent X` via matrix. - README grows a "Multi-agent workspaces" section with `expert.toml` sample. - `docs/AGENT_E2E_SETUP.md` gains a matrix snippet for monorepo integrations. ## Tests - 20 new unit tests for `workspace.py` covering every precedence rule, prefix matching, state file round-trips, and API-key env resolution. - 14 new tests for the argv rewriter + CLI integration of `agents`/`use`/`which`. - All 85 existing + new tests green; ruff + mypy clean. Made-with: Cursor

- Bump default Gemini model used for `count-tokens` and `GeminiAIStudioClient.DEFAULT_MODEL` from the now-unavailable `gemini-2.0-flash-exp` to `gemini-2.5-flash`. The old model returns 404 NOT_FOUND on the v1beta API. - Resolve `expert.__version__` via `importlib.metadata` instead of hardcoding; the literal `"0.1.0"` had drifted from `pyproject.toml` (now `0.1.1`) and will drift again on every release-please bump. - Type `ExpertLibrary.run_cli.expect_rc` as `int | None` so Robot Framework's dynamic-argument converter accepts `${None}` from suites without trying to coerce it into int (which raised ValueError and failed suites 01_validate / 03_update that use `expect_rc=${None}` to tolerate count-tokens failures). Made-with: Cursor

@alias

Replaces `ecg-expert` / `ECG_*` with `my-expert` / `MY_EXPERT_*` across docstrings, test fixtures, and public-facing docs. The previous naming was descriptive but risked anchoring readers on a specific downstream use case; the framework is domain-agnostic. - cli/expert/workspace.py: TOML schema docstring - cli/tests/test_workspace.py: discovery / resolution fixtures - cli/tests/test_main_alias.py: @alias rewriter + integration fixtures - docs/AGENT_E2E_SETUP.md: placeholders, matrix example, CLI walkthrough - .github/workflows/expert-e2e.yml: usage comment No behavioural change; all 88 unit tests pass. Follows the guidance in downstream `PRIVATE_AGENT_REPO.md` (§6) to keep public examples neutral. Made-with: Cursor

Switches the project license from Apache-2.0 to MIT: - LICENSE: full MIT text (Copyright 2026 Felipe Broering) - pyproject.toml: `license = { text = "MIT" }` + MIT classifier Rationale: MIT is simpler, more permissive, and better matches the expectations of the target audience (researchers, hobbyists, small teams shipping niche experts). No patent grant is sacrificed that matters at this stage; contributions so far are all first-party. Made-with: Cursor

Adds a shared, reusable visual identity for the CLI and tightens the existing Rich helpers. - cli/expert/brand.py (new): renders the ANSI-shadow wordmark, the tagline, and — optionally — the installed version + license line. - cli/tests/test_brand.py (new): golden-style checks for the brand renderer (structure, keywords, version line presence). - cli/expert/main.py: `expert --version` now prints the full brand block; also exposes a hidden `expert brand` command. - cli/expert/ui.py: emoji-free, single-glyph prefixes for success/error/warning/info (✓ / ✗ / ⚠ / >) and three new helpers (`print_hint`, `print_step`, `print_kv`) for consistent spacing. - cli/tests/test_init.py: tracks the new output formatting. All existing tests stay green. Made-with: Cursor

Rounds out the repo for a public launch: contributor docs, a voice that matches the new brand block, and a companion guide for the downstream private repos this framework exists to serve. ## Governance - AGENTS.md: canonical contributor agreement + agent guidance. - CONTRIBUTING.md: how to file issues, open PRs, run the checks locally, and interact with the CI kit. - CODE_OF_CONDUCT.md: Contributor Covenant v2.1. - SECURITY.md: responsible-disclosure policy and rotation guidance. ## Templates - .github/ISSUE_TEMPLATE/bug_report.yml - .github/ISSUE_TEMPLATE/feature_request.yml - .github/ISSUE_TEMPLATE/config.yml (disables blank issues, points at security + discussions) - .github/PULL_REQUEST_TEMPLATE.md ## Docs - docs/PRIVATE_AGENT_REPO.md: step-by-step playbook for spinning up a private agent repo that consumes `expert-agent` as a library — layout, `expert.toml` conventions, CI wiring, secret hygiene, red flags. - README.md: rewritten to lead with the tagline, surface the new multi-agent workspace story, and link to the private-agent-repo guide. Made-with: Cursor

feliperun added 6 commits April 17, 2026 16:17

feliperun merged commit a35a034 into main Apr 17, 2026
4 checks passed

feliperun deleted the feat/brand-launch branch April 17, 2026 21:07

github-actions Bot mentioned this pull request Apr 17, 2026

chore(main): release 0.1.2 #2

Merged

feliperun mentioned this pull request Apr 17, 2026

feat(cli): multi-agent workspaces with @alias, expert.toml and expert use #3

Closed

6 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: public launch — MIT license, brand block, governance, and multi-agent workspaces#4

feat: public launch — MIT license, brand block, governance, and multi-agent workspaces#4
feliperun merged 6 commits into
mainfrom
feat/brand-launch

feliperun commented Apr 17, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

feliperun commented Apr 17, 2026

Summary

Commits (bottom → top of the branch)

1. feat(cli): multi-agent workspaces with @alias, expert.toml, and expert use

2. fix: ship correct defaults for count-tokens, __version__, and testkit

3. chore: use synthetic agent names in examples and fixtures

4. chore(license): relicense under MIT

5. feat(cli): brand block + refined glyphs

6. docs: add governance, PR/issue templates, and private-agent-repo guide

Test plan

Notes for reviewers

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

1. `feat(cli): multi-agent workspaces with @alias, expert.toml, and expert use`

2. `fix: ship correct defaults for count-tokens, version, and testkit`

3. `chore: use synthetic agent names in examples and fixtures`

4. `chore(license): relicense under MIT`

5. `feat(cli): brand block + refined glyphs`

6. `docs: add governance, PR/issue templates, and private-agent-repo guide`