Agent implementation guide

Rules and commands for coding agents that create or modify Fentaris projects.

Use this guide when Codex, Claude Code, or another coding agent is implementing a Fentaris project. The goal is to produce runnable code, leave secrets with the user, and verify the proxy before handoff.

Quick Start

Read the docs index first, then inspect the local project:

curl -s https://fentaris.mintlify.app/llms.txt
ls
test -f fentaris.json && cat fentaris.json

Prefer the high-level API for new code:

import { fentaris, group, mcp, policy, stdio, user } from "@fentaris/core";

Run validation before handoff:

fentaris check --offline
fentaris doctor
fentaris secrets manifest --check
FENTARIS_API_KEY="<api-key>" fentaris doctor --runtime

Implementation Rules

Use fentaris(...), mcp(...), stdio(...), streamableHttp(...), group(...), user(...), and policy(...) for new projects. Use class constructors only when an existing project already uses them or when a low-level integration requires them.

Do not invent, print, or commit real secrets. Leave FENTARIS_AUTH_KEY, raw API keys, and upstream tokens for the user unless they explicitly request disposable local values. When a project needs secrets, write the TypeScript credential references and hand off exact fentaris auth or fentaris secrets commands.

Keep authorization durable. Put stable access control in policy(...) and group declarations. Use middleware, hooks, and local operation handlers for runtime checks, logging, validation, and side effects after policy has allowed a capability.

API Decision Table

Goal	Use	Avoid / note
Declare an upstream MCP server	app.mcp("name", options) or mcp("name", options)	app.group(...).mcp(...) does not declare a server
Add app-owned tools, resources, prompts, or completions	app.local("name")	Local namespace names must not collide with upstream server names
Add static authorization	policy("name").mcp("server").allow("tool")	Middleware should not replace durable policy
Add runtime argument checks	app.mcp("server").tool(...), app.local(...).tool(...), or middleware	Policy does not inspect arbitrary tool arguments
Enable per-user API-key auth	projectVaultIdentityStrategy(...) and fentaris auth keys create	Do not generate or store raw API keys in app code
Reference upstream credentials	credential("github.token"), credentialJson(...), or credentialEnv(...)	Secret values stay outside committed TypeScript
Store group-owned credentials	group({ credentials: { "github.token": credentialVault("github.team.token") } }) plus fentaris secrets set github.team.token	Keep storage references separate from access policies
Add local-only development access	Policy.allowAll() only in disposable examples	Production proxies should use least-privilege policy(...) rules
Place work on an edge target	app.target(...) plus the target binding API documented for the edge flow	Target binding does not grant policy access
Add group-scoped governance incrementally	app.group(id).users(...).policy(...)	Fluent group handles do not own credential sources

Handoff Checklist

Before returning the project, include:

• files changed
• commands run and their result
• commands the user must run to provide secrets
• MCP endpoint, usually http://localhost:4000/mcp
• API key header, usually x-fentaris-api-key
• expected allowed and denied test cases

Use this handoff shape:

Run:
export FENTARIS_VAULT_KEY="<explicit-vault-unlock-key>"
fentaris auth keys create --user alice --name workstation
printf '%s' "$GITHUB_TOKEN" | fentaris secrets set github.maintainers.token --stdin --non-interactive
fentaris secrets manifest --check
fentaris doctor --runtime

Review Checklist

Use this checklist before accepting work produced by Codex, Claude Code, Cursor, Pi, or another coding agent. A generated patch is not complete until a reviewer can answer every item from the diff and verification evidence.

Scope and intent

• Re-read the original prompt, linked task, and acceptance criteria.
• Map each changed file to one requested outcome.
• Reject unrelated refactors, dependency upgrades, formatting sweeps, generated output, or configuration changes unless they are explicitly justified.
• Confirm that omitted requirements and known limitations are called out in the handoff.

Manual diff review

• Read the complete diff, including tests, lockfiles, generated files, workflows, and deletion changes.
• Trace user-controlled input through validation, authorization, side effects, errors, and cleanup.
• Check failure, cancellation, retry, concurrency, and partial-write paths rather than reviewing only the success path.
• Verify that public commands, types, config, output, and documentation still agree.

Security and privacy

• Search the diff and test output for API keys, tokens, passwords, private URLs, personal data, .env contents, and decrypted credentials.
• Confirm that logs and errors redact secret-bearing values and do not expose full request arguments by default.
• Confirm that new access paths fail closed and preserve Fentaris identity, policy, and approval checks.
• Verify that files containing local credentials remain ignored and use restrictive permissions where supported.

Verification

• Run the narrowest relevant tests first and inspect the asserted behavior.
• Run pnpm lint, pnpm typecheck, pnpm build, and pnpm -r test from a clean dependency install.
• For published-package changes, pack and install the candidate tarballs in an empty project instead of testing only workspace links.
• Exercise at least one expected success and one expected denial or failure through the real CLI, SDK, or MCP endpoint.
• Record skipped checks with the exact blocker; do not report an unrun command as passing.

Acceptance and traceability

• Compare observed output with every acceptance criterion and the original prompt.
• Confirm the handoff names changed files, commands run, results, release impact, and remaining operator actions.
• Record the run in AI Agent Runs with the prompt or task link, agent, branch or commit, review owner, verification evidence, decision, and follow-up work.
• Require human review before merge for any non-trivial generated change.

Related Documentation

• Team-governed proxy
• Governance auth
• Proxy setup
• API reference map