From 6a0f191f73f68b4808014d41653209a9cf27dc15 Mon Sep 17 00:00:00 2001 From: Christopher Tso Date: Thu, 2 Jul 2026 11:07:53 +0200 Subject: [PATCH 1/3] docs(agents): clarify research and tracker source of truth --- .agents/product-boundary.md | 2 +- .agents/workflow.md | 5 ++++- AGENTS.md | 3 ++- 3 files changed, 7 insertions(+), 3 deletions(-) diff --git a/.agents/product-boundary.md b/.agents/product-boundary.md index b93614b84..6c4eec093 100644 --- a/.agents/product-boundary.md +++ b/.agents/product-boundary.md @@ -80,7 +80,7 @@ Use public reference standards before inventing AgentV-specific contracts: - Hugging Face Datasets for dataset, split, record, and portable corpus conventions. - OpenInference for trace, span, tool-call, and model-observability semantics. -Research those references from local cloned repositories first when a clone is available, and use DeepWiki MCP for repository-level orientation or cross-repo questions. Broad web search is a fallback, not the default. If current public documentation matters for the decision, use official docs and record the exact source or commit alongside the conclusion. +Research those references from local cloned repositories first when a clone is available, and use DeepWiki MCP for repository-level orientation or cross-repo questions. In this operator workspace, Promptfoo is available at `/home/entity/projects/promptfoo/promptfoo` with DeepWiki repo `promptfoo/promptfoo`, and DeepEval is available at `/home/entity/projects/confident-ai/deepeval` with DeepWiki repo `confident-ai/deepeval`. Use `rg` and `git` in those clones for exact code evidence, and record the clone commit with conclusions that depend on source behavior. Broad web search is a fallback, not the default. If current public documentation matters for the decision, use official docs and record the exact source URL or commit alongside the conclusion. Treat these as reference inputs, not dependencies. AgentV should adopt the shared lowest common denominator when it fits the repo-native artifact model, and document any intentional divergence in the relevant plan, ADR, or contract docs. diff --git a/.agents/workflow.md b/.agents/workflow.md index 221d92107..dfe1256db 100644 --- a/.agents/workflow.md +++ b/.agents/workflow.md @@ -5,8 +5,10 @@ This file expands [AGENTS.md](../AGENTS.md) for day-to-day repo work: tracker ha ## Tracker and Repo Safety - Treat task-tracking instructions as operator-supplied context. If the prompt provides an external tracker database, path, or environment variable, use that exact tracker for assignment, status, dependencies, handoff notes, decomposition, and resumability. +- When Beads is the supplied tracker, each Bead is the authoritative work packet for its scope. Keep descriptions, acceptance criteria, and notes self-contained enough that a worker can act from the Bead plus required AGENTS routing docs. Plans, PR comments, and chat decisions can be linked as supporting evidence, but they must not be the only place a live decision exists once Beads have been created. +- If you discover a Bead conflicts with a plan, ADR, PR comment, or current implementation, stop and update or escalate the Bead before dispatching workers. Do not rely on workers to reconcile stale plan text independently. - If no external tracker is supplied, work from the user's prompt and the current branch or PR. Do not create, sync, stage, or commit repo-local tracker state unless the user explicitly requests it. -- Keep private launcher names, local paths, session aliases, dispatch policy, and operator workspace details outside this public repository. +- Keep private launcher names, session aliases, dispatch policy, and ad hoc operator workspace details outside this public repository. Do not add local paths except stable operator-provided reference clone paths that AGENTS.md intentionally documents for worker research. - GitHub remains the PR, CI, review, and merge surface. Use GitHub Issues or Projects for external collaboration only when the user or operator explicitly asks for that workflow. - Do not add repo-local tracker directories, tracker JSONL exports, dispatch logs, cross-repo research records, or operator decision records to AgentV commits unless the user explicitly asks for repository-local tracker artifacts. - Do not commit project-local coordination config files. @@ -51,6 +53,7 @@ bd where ## Research, Build, and Artifact Reuse +- For peer-framework and external-codebase research, inspect local clones and DeepWiki before using broad web search. Known local reference clones in this operator workspace are Promptfoo at `/home/entity/projects/promptfoo/promptfoo` and DeepEval at `/home/entity/projects/confident-ai/deepeval`; use DeepWiki repos `promptfoo/promptfoo` and `confident-ai/deepeval` for architecture orientation. Verify implementation details with `rg`, `git log`, and source files in the clone, and record the clone commit or official-doc URL behind the conclusion. - Research-only workers should inspect files and repository history without running `bun install`, `bun run build`, tests, or evals unless the assigned research explicitly depends on that command. Record the justification when a research worker does run one of those commands. - Do not copy mutable build outputs from `main` or another worktree as the default way to avoid local builds. Prefer the commit-addressed CI build artifact when one is available for the exact source state. - A prebuilt CI artifact may be reused only when its manifest matches the consumer's commit SHA, `bun.lock` SHA-256, runner OS/architecture, expected Bun version source/value, and required output paths. diff --git a/AGENTS.md b/AGENTS.md index 2ce40e194..1774ff5d3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -26,7 +26,7 @@ Design guardrails: - Document composition patterns before inventing a new feature. - Match industry-standard lowest-common-denominator contracts when possible. - When designing AgentV contracts, check public reference standards such as Claude Skills, Vercel agent-eval, Hugging Face Datasets, and OpenInference before inventing AgentV-specific shapes. Use their shared lowest common denominator where it fits, and document any intentional divergence. -- For peer-framework research, prefer local cloned repositories and DeepWiki MCP over broad web search. If a public contract must be checked for currentness, use official docs and record the source or commit behind the conclusion. +- For peer-framework research, use local cloned repositories and DeepWiki MCP before broad web search. In this operator workspace, Promptfoo is cloned at `/home/entity/projects/promptfoo/promptfoo` and DeepEval is cloned at `/home/entity/projects/confident-ai/deepeval`; use DeepWiki repos `promptfoo/promptfoo` and `confident-ai/deepeval` for architecture-level orientation, then verify exact claims with `rg` and `git` in the local clone. If a public contract must be checked for currentness, use official docs and record the source URL or clone commit behind the conclusion. - Apply YAGNI aggressively and solve the current request with the smallest surface that works. - Keep extensions non-breaking unless a same-week unreleased surface should be hard-corrected. - Design for AI comprehension with self-describing modules, clear extension points, and no dead scaffolding. @@ -40,6 +40,7 @@ These baseline rules apply to every repo change. They summarize the most common - Start every repo change with `git fetch origin` and `git status --short --branch`. - Use `bun` for package and script operations. - Use the operator-supplied tracker when present. Do not commit tracker runtime state, local coordination config, or other machine-local artifacts. +- When Beads are available, treat Beads as the worker-facing source of truth for task scope. Write each Bead description, acceptance criteria, and notes so a worker can execute from the Bead plus required AGENTS routing docs; do not require workers to read a merged or stale plan to discover the current decision. If a plan, PR comment, chat decision, or ADR supersedes earlier guidance, update the Bead before dispatching or continuing work. - Do not use `git stash` on shared checkouts. Stage explicit paths only, and never push directly to `main`. - Every merge to `main` requires a GitHub pull request with passing GitHub Actions. Do not locally merge feature or integration branches into `main` as a substitute for opening a PR. - Prefer the primary checkout only for small, clean, bounded work. Use a dedicated worktree from the latest `origin/main` for non-trivial, risky, long-running, or parallel changes. From cab202c107a8a2edbfa03c3b5eea7ad0311e88bc Mon Sep 17 00:00:00 2001 From: Christopher Tso Date: Thu, 2 Jul 2026 11:13:45 +0200 Subject: [PATCH 2/3] docs(targets): document cc-mirror via claude executable --- .../docs/docs/targets/coding-agents.mdx | 25 +++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/apps/web/src/content/docs/docs/targets/coding-agents.mdx b/apps/web/src/content/docs/docs/targets/coding-agents.mdx index a6fe0776f..2e0ebd744 100644 --- a/apps/web/src/content/docs/docs/targets/coding-agents.mdx +++ b/apps/web/src/content/docs/docs/targets/coding-agents.mdx @@ -73,6 +73,31 @@ targets: | `cwd` | No | Working directory | | `grader_target` | Yes | LLM target for evaluation | +### cc-mirror variants + +[cc-mirror](https://github.com/numman-ali/cc-mirror) creates Claude Code +variant binaries that route through alternative providers such as Z.ai, Kimi, +MiniMax, or OpenRouter. In AgentV, configure those variants as Claude targets +with an explicit `executable`: + +```yaml +targets: + - name: claude_zai + provider: claude + executable: claude-zai + grader_target: azure-base +``` + +Create the variant first, then reference the generated binary name: + +```bash +npx cc-mirror quick --provider zai --name claude-zai --api-key "$Z_AI_API_KEY" +``` + +Use `provider: claude` or `provider: claude-cli` for these targets. The old +`provider: cc-mirror` alias and automatic `variant.json` lookup are no longer +part of the canonical target schema. + ## Codex CLI ```yaml From c100985fe0214179181acd43f4c7650b1bc1277f Mon Sep 17 00:00:00 2001 From: Christopher Tso Date: Thu, 2 Jul 2026 11:14:24 +0200 Subject: [PATCH 3/3] docs(targets): use kebab case cc-mirror target name --- apps/web/src/content/docs/docs/targets/coding-agents.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apps/web/src/content/docs/docs/targets/coding-agents.mdx b/apps/web/src/content/docs/docs/targets/coding-agents.mdx index 2e0ebd744..6f1ce13d4 100644 --- a/apps/web/src/content/docs/docs/targets/coding-agents.mdx +++ b/apps/web/src/content/docs/docs/targets/coding-agents.mdx @@ -82,7 +82,7 @@ with an explicit `executable`: ```yaml targets: - - name: claude_zai + - name: claude-zai provider: claude executable: claude-zai grader_target: azure-base