mivia-agent

Imported from MiviaLabs/mivia-agent (AGENTS.md). Install upstream with npx skills add MiviaLabs/mivia-agent. Copyright stays with the author.

Agent Instructions

Product: mivia (MiviaLabs) Module: github.com/MiviaLabs/mivia-agent Binary: mivia (cmd/mivia/) Predecessor: mivia-agentkit MVP (legacy CLI name mivia-agent; patterns reused, product identity is new)

Canonical surfaces

1. This file (AGENTS.md) - short overview, non-negotiables, and the rules/doctrines index below
2. .agents/INDEX.md - fuller control-surface index (skills, policy, quality, hooks, semgrep)
3. .agents/doctrines/* - evidence and verification doctrines
4. .agents/rules/* - durable policy (linked by title below)
5. .agents/skills/* - real-directory skills under the development surface; the mivia binary's loader (internal/workspace.SkillsDir) reads from this path. Claude Code discovers skills only under .claude/skills/, so .claude/skills/<name>/SKILL.md is an alias stub that repeats the canonical frontmatter and points at the canonical file. It is a plain file, not a symlink, because Git sets core.symlinks=false on Windows by default
6. docs/OWNERS.yaml - doc ownership map; ADRs are prohibited
7. Thin adapters only: CLAUDE.md, .claude/, .codex/, .github/

Do not fork policy into adapters. Fix .agents/ or this file instead.

.mivia/ is scoped to the product's own runtime config and state, not agent instructions: mivia.toml (this repo's own dogfooded config), workflows/* (the workflow engine's definitions, read at runtime by internal/tools/workflow_tools.go), hooks/ (this repo's lifecycle hook scripts), policy/* (commit-message, pr-title, go-structure, docs-ownership, agent-hook-bypass - all read by compiled Go code or scripts at a hardcoded .mivia/policy/ path). Never move those; they are functional, not instructional. .mivia/ holds no skills: workspace skills live only in .agents/skills/, which is the path internal/workspace.SkillsDir reads.

.agents/memories/

.agents/memories/*.md is team-shared, cross-tool operational memory - facts and corrected preferences about how to work in THIS repo, not policy - following the open .agents protocol (https://dotagentsprotocol.com/). Format and conventions live in .agents/memories/README.md. It is git-committed, so it is not a substitute for .agents/rules/* (durable policy) or a private per-machine agent memory store; a fact that becomes a hard rule belongs in .agents/rules/, not here.

Read every file under .agents/memories/ at the start of a task, the same way you read this file. .agents/memories/.archive/ is the one exception: an archived memory is a record, not an active constraint.

.agents/agents/

Markdown subagent role definitions with YAML frontmatter: planner.md, plan-reviewer.md, builder.md, reviewer.md, and specialist roles. There is deliberately no mivia.md root-agent override: the root session runs the compiled fallback prompt the shipped binary carries, so this repo dogfoods exactly what users get. Format and loading contracts are documented in .agents/agents/README.md. Run make agents-check after editing any role file.

planner.md and plan-reviewer.md are standalone, manually-selectable roles (pick them from the agent switcher, or dispatch them by name) for ad-hoc plan drafting and challenge outside any automated loop. Neither the ADLC rule's own Step 0 dispatch example nor the compiled workflow engine calls them by name: Step 0 there dispatches the generic reviewer (+ architecture-review skill) and auditor roles. The compiled workflow engine's shape varies by workflow: .mivia/workflows/feature-delivery.toml uses workflow-engineer for plan/implement/repair steps and a panel-reviewer/review-synthesizer panel for review, while bug-fix.toml/bug-fix-fast.toml instead gate review with an active agent = "reviewer" triage step (their panel/review layers are currently commented out in the checked-in workflow TOMLs as a temporary debug cut). Do not assume either automated path routes through planner.md/plan-reviewer.md - it does not, today.

Delivery process

For substantial feature work, bug fixes, refactors, and cross-package changes, use the delivery skill: it routes through the ADLC loop (Plan→Breakdown→Validate→Finalize→Implement (TDD)→Audit→Commit) and points at the canonical rule (.agents/rules/05-adlc-agentic-development-lifecycle.md) and role files rather than duplicating them. Step 0 there is a hostile challenge of the plan before any code is written; Step 5 is a hostile bug audit loop until zero bugs found.

Small, well-understood changes (the Fast Path: ≤5 lines, single file, no new types, is always in this bucket) do not need the skill - read the code, make the change, verify it, and say what you verified. Use judgment for anything larger; when the plan or blast radius is unclear, prefer the skill over guessing.

Rules

Doctrines

Source-of-truth order

1. System / tool instructions
2. .agents/ (rules, doctrines, skills) and .mivia/ (product runtime config/state)
3. AGENTS.md
4. Task prompt

Non-negotiables

• Correctness, security, privacy, maintainability over speed
• No secrets, raw prompts, raw model dumps, or PII in commits/logs/fixtures
• Never bypass Git hooks (bypass flags, Husky/Lefthook skip env, etc.). Enforced at three layers off ONE policy file, .mivia/policy/agent-hook-bypass.json: the Git hooks themselves, scripts/agent_hook_guard.py for adapter agents, and a PreToolUse lifecycle hook this repo declares in .mivia/mivia.toml that refuses such a run_command. Update the JSON; never fork the patterns into a copy.
• Subagents are tasks/goroutines with shared pools - not process-per-agent by default
• Update owned docs only (docs/OWNERS.yaml); no parallel policy docs
• Never claim a check passed unless it was executed
• All agent-authored prose must use ASD-STE100 Simplified Technical English (STE). See 90-writing-standard-ste100.
• Ship binary name is mivia only
• UI packages are self-contained: internal/tui/view/** and internal/tui/kit/** must not import internal/cli*, internal/chat, internal/agent, internal/coordinator, or internal/hub. internal/tui/view/** and internal/tui/kit/** connect only through internal/tui/kit/ports and the internal/tui/kit/uievent vocabulary. internal/tui/adapter is the sole integration bridge, isolated from UI packages and CLI entrypoints per INV-TUI-29. Enforced by Go tests in internal/tui/adapter/ and scripts/check_import_layers.py; policy: docs/design/ui-isolation.md.
• Model-facing tools + compiled default prompts are project/language-generic (any user workspace). Host code may be Go; do not bake Go/cmd/mivia into tool Description() or defaultAgentPrompt. Rule: 60-tools-project-language-generic. Enforced by internal/tools/generic_surface_test.go and internal/cli/chat/prompt_generic_test.go.
• No spaghetti growth: prefer files ≤500 LOC and functions ≤80 LOC (hard 800 / 120). Staged files ≤500 KiB. Policy .mivia/policy/go-structure.json; gate scripts/check_go_structure.py + file-size-check. Do not raise baselines to silence failures - split code.
• Never run go test -fuzz with default parallelism. Go fuzzing spawns one worker per core, each with unbounded memory; on this machine it reaches ~55 GB RSS and the kernel OOM kill takes down the whole desktop app. If fuzzing is required, cap it: go test -fuzz <Target> -parallel 2 -fuzztime 60s. Seeded smoke runs (go test, no -fuzz flag) are always fine. Gate: .mivia/policy/resource-exhaustion.json via the PreToolUse run-command-guard.py; contract tests in scripts/test_agent_hook_guard.py.

Local commands

make install-hooks   # once per clone
make verify          # offline gates (config, secrets, docs, contracts, semgrep, go)
make test
make test-changed    # go test on packages with uncommitted/staged .go changes only
make race            # concurrency packages
make build           # produces ./mivia
make secret-scan
make docs-check
make semgrep

Workflow runs

Start every feature-delivery run with scripts/run-delivery-workflow.sh <label>; the script sets --allow-publish and starts the run in the background. It prints the log path.

Never run a live e2e workflow (e2e-split-test, e2e-pr-metadata-test, e2e-scope-escape-test), the e2e suite runner, or the context-compaction e2e without the user explicitly asking for it in that session. They are not part of make verify, CI, or any automated path. Runbook and commands: docs/development/agent-workflow.md.

Layout

cmd/mivia/           CLI entrypoint -> binary mivia
internal/            Go packages
internal/tui/            Interactive TUI grouping dir (no package)
internal/tui/kit/        Ports, keymap, events (no bubbletea)
internal/tui/view/       Screens, components, render, theme
internal/tui/adapter/    Session-to-ports bridge
internal/tui/run/        Composition root (cmd/mivia wires RunTUI)
internal/cli/            CLI composition root (package cli: command wiring)
internal/cli/worktree/   Worktree/session-dir command support
internal/cli/agents/     Agent registry + agent command surfaces
internal/cli/orchestrate/ dispatch_tasks/join_run tool layer
internal/cli/workflow/   Workflow engine, delivery, progress
internal/cli/chat/       Chat REPL, slash commands, session tools
internal/cli/automations/ Automation run/serve command surfaces
internal/provider/      Provider clients, streaming, usage (package provider)
internal/provider/registry/   Provider name -> client registry map
internal/provider/reasoning/  Reasoning effort/budget mapping
internal/context/       Context lifecycle grouping dir (no package)
internal/context/manager/     Context manager (commit, planner, summaries)
internal/context/state/       Turn/session state contracts
internal/ledger/core/   Ledger engine primitives (package core)
internal/hooks/session/ Running session hook state (package session)
.agents/             Canonical agent control surface (rules, doctrines, skills, quality, templates, agents/*.md)
.mivia/              Product runtime config/state: mivia.toml, workflows/, hooks/, policy/*
.mivia/hooks/        This repo's own mivia lifecycle hook scripts (project-scoped)
docs/                Human docs (OWNERS enforced)
scripts/             Guards, hooks, scans, contract tests
semgrep/             Agent-standards static rules
.githooks/           core.hooksPath entrypoints

Workflows

When the workspace has .mivia/workflows/, the root agent has the workflow tools by default. workflow_run admits and starts a named workflow. workflow_status, workflow_events, workflow_inspect, and workflow_list_runs observe runs. workflow_deliver publishes a delivery-pending run, but only with allow_publish=true. workflow_cancel stops a run. Use the workflow engine when a task fits an existing workflow definition.

Git commits

Format (scope required):

type(scope): imperative subject

Policy SoT: .mivia/policy/commit-message.json

There is no setup scope. Bootstrap/control-surface work uses ai, hooks, quality, or build.

On commit-msg failure the hook prints allowed types and scopes first, then the error.

Completion report

The report shape (Outcome, Changed files, Verification, Residual risk) is defined in 01-output-budget. Formal audits: .agents/templates/agent-report-v1.md (mivia-report/v1). Bug-audit: skill-specific finding format only.