mistralai Create Vibe Feature
Use this skill when implementing Vibe feature work. Keep changes scoped, architecture-aware, and consistent with nearby code.
App Areas
| Area | Role | Path |
|---|---|---|
| Core engine | Agent loop, domain events, tools, LLM backends, config, sessions, skills, hooks, telemetry types, shared models | vibe/core/ |
| Textual CLI | Interactive terminal UX, widgets, slash commands, manual shell commands, voice UI, local user affordances | vibe/cli/ |
| ACP bridge | Agent Client Protocol session, tool, terminal, title, and content translation | vibe/acp/ |
| Setup | First-run, auth, onboarding, trusted folders, update prompts | vibe/setup/ |
| Tests | Unit, integration, e2e, Textual snapshots, stubs and fixtures | tests/ |
Architecture Routing
Before implementation, read the matching ADRs:
- Architecture principles, module boundaries, startup/runtime speed, simple changes:
docs/adr/0001-architecture-principles.md - Core engine vs delivery surfaces:
docs/adr/0002-core-engine-and-delivery-surfaces.md - Agent loop orchestration, streaming, events, cancellation, responsiveness:
docs/adr/0003-event-driven-agent-loop.md - Tool contracts, permissions, output, UI metadata, adapters:
docs/adr/0004-typed-permissioned-tools.md - Config models, layering, defaults, migrations, reloads:
docs/adr/0005-layered-configuration.md - Session logging, resume, rewind, transcript metadata, migrations:
docs/adr/0006-local-sessions.md - Skills, agents, subagents, hooks, MCP, connectors, custom tools, discovery:
docs/adr/0007-extension-mechanisms.md - Feature work, telemetry events, analytics properties, instrumentation verification:
docs/adr/0008-feature-instrumentation.md
If a change fits the current code but conflicts with ADR direction, flag it to the user before implementing.
Workflow
- Read
README.md,AGENTS.md, and the nearest relevant source files before editing. - Identify the owning area. Keep UI behavior in
vibe/cli, ACP translation invibe/acp, setup flow invibe/setup, and reusable engine behavior invibe/core. - Study one or two existing features with the same shape before adding new files. Match naming, model placement, port/adapters, tests, and error patterns.
- Prefer a small change in the owning module. Add a port or abstraction only when it protects a meaningful boundary or makes replacement/testing easier.
- For feature work, plan telemetry with
instrument-feature-analyticsbefore writing tracking code. - Keep startup and interactive latency in mind. Avoid eager imports, broad scans, and network or subprocess work unless the configured feature needs them.
- Update docs or built-in skill guidance when the feature changes user-visible CLI behavior, config, commands, agents, persistence, or discovery.
Tools
When adding or modifying a tool:
- Subclass
BaseToolfromvibe/core/tools/base.pywith a Pydantic args model and aBaseToolConfiggeneric parameter. - Implement
async def run(args, ctx: InvokeContext)and yield events progressively. - Raise
ToolErrorfor user-facing failures; raiseToolPermissionErrorfor authorization failures. - Declare permission with
ToolPermission(ALWAYS/ASK/NEVER); honor it consistently.
Consistency Checks
- Core code should not import Textual, ACP schemas, setup UI, or other delivery-surface details.
- Surface code should adapt core events/models instead of reaching into private core state.
- External data should enter through Pydantic validation, typed events, tool args/results, config models, or explicit ports.
- Tools should follow
BaseToolwith typed args, result, config, state, and permission behavior. - Tests should mirror the source layout and use existing fixtures or
tests/stubs/Fake*doubles.
Verification
After Python changes, run:
uv run ruff format .
uv run ruff check --fix .
For behavior changes, run the narrowest relevant tests first, then broader checks if the change touches shared contracts:
uv run pytest <path-or-test>
uv run pyright