Agon

Multi-agent AI analysis that transforms raw ideas into production-ready documentation.

Why the name "Agon"?
Agon comes from the Greek ἀγών (agōn), meaning a contest, struggle, or formal debate.
The name fits this product because ideas are stress-tested through structured multi-agent debate before producing final execution artifacts.

---

Table of Contents

Back to top

• What is Agon?
• How to Run Agon
  • CLI Application
  • Web Application
  • iOS Application
  • Local Deployment (Developer Runbook)
  • Worktree-Based Local Testing (Feature Branch)
• Repository Structure
• Development Guide
  • Developer Setup Guide (Infrastructure)
  • CLI (TypeScript)
  • Backend (.NET)
  • Frontend (Next.js)
• Testing and Quality
  • Running Tests
  • Pre-Merge Validation Protocol
• CLI Release Process
• Architecture Documentation
• Current Status
• Contributing to Agon
  • Reporting Issues and Feature Requests
  • Submitting Pull Requests
• License
• Notes for Project Maintainers

---

Project Overview

Back to top

Agon transforms raw ideas into production-ready documentation through structured multi-agent analysis. You submit a product concept, technical proposal, strategic decision, or just a simple question, and a council of AI agents (powered by OpenAI GPT, Google Gemini, and Anthropic Claude) collaboratively analyze it across multiple rounds to produce:

• Verdict — Executive summary with go/no-go recommendation
• 30/60/90 Day Plan — Phased implementation roadmap
• Product Requirements Document (PRD) — Full specifications with acceptance criteria
• Risk Registry — Identified risks with severity, likelihood, and mitigation strategies
• Assumption Validation — Critical assumptions requiring validation before execution
• Architecture Overview — Technical design and system topology (Mermaid diagrams)
• Copilot Instructions — Implementation guidance for development

How It Works

Back to top

1. Clarification Phase: A Moderator agent asks clarifying questions to refine your idea into a structured "Debate Brief"
2. Analysis Round: Three council agents (GPT, Gemini, Claude) independently analyze your idea in parallel, each adding claims, assumptions, and risks to a shared Truth Map
3. Critique Round: Each agent critiques the other two agents' work, challenging assumptions and refining confidence scores
4. Synthesis: A Synthesizer agent unifies all perspectives into coherent, decision-grade artifacts
5. Post-Delivery Follow-Up: Continue the conversation — ask questions, challenge claims, or request revisions through an interactive shell

The Truth Map is the authoritative session state — a structured graph of claims, assumptions, risks, and decisions with full provenance tracking. All artifacts are generated from this map, never from raw conversation transcripts. If constraints change mid-session, the system automatically recalculates impact and agents reevaluate affected claims.

---

Installation

Back to top

Agon can be accessed through multiple interfaces. The CLI is currently available, with web and mobile applications in development.

CLI Application (Available Now)

Back to top

The Agon CLI is distributed as an npm package: @agon_agents/cli.

Prerequisites

Back to top

• Node.js 20+ (download)
• npm (included with Node.js)

Installation Methods (Global, npx, Local)

Back to top

1) Global Installation (Recommended for daily use)

Back to top

Install globally to run agon from any terminal directory:

npm install -g @agon_agents/cli

Verify installed version:

agon --version

Launch shell:

agon

Inside the shell, run:

/help

Update global install to latest stable:

npm install -g @agon_agents/cli@latest

Advantages:

• agon works everywhere on your machine
• Best startup speed for frequent use

Disadvantages:

• Requires global npm install permissions
• Version is shared across all projects on your machine

2) npx (No permanent install)

Back to top

Run without a global install:

npx @agon_agents/cli

Check version:

npx @agon_agents/cli --version

You can force the newest release explicitly:

npx @agon_agents/cli@latest

Advantages:

• No global install required
• Easy one-off usage

Disadvantages:

• Usually slower startup than global install
• Can depend on registry/network availability when not cached

3) Local Project Installation (version-pinned per repo)

Back to top

Install into your project:

npm install --save-dev @agon_agents/cli

Add script in package.json:

{
  "scripts": {
    "agon": "agon"
  }
}

Run:

npm run agon

Check local installed version:

npm exec -- agon --version

Advantages:

• Version is pinned in project lockfile (reproducible team setup)
• No global dependency required

Disadvantages:

• Not directly available as agon outside that project
• Usually invoked via npm run / npm exec

Uninstalling

Back to top

Remove global installation:

npm uninstall -g @agon_agents/cli

Remove local project installation:

npm uninstall @agon_agents/cli

Quick Start (Current Shell-First UX)

Back to top

After launching agon, use these in-shell commands:

/help
/new
/show-sessions
/resume [session-id]
/session <session-id>
/status [session-id]
/status
/show verdict
/refresh verdict
/attach "./docs/product-brief.pdf"
/follow-up "<your request>"
/update [--check]
/exit

Notes:

• agon --version prints the installed CLI version and exits.
• agon --help shows launcher help.
• agon --self-update updates the global CLI install from terminal.
• /update runs the same update flow from inside an active shell session.
• By default, Agon CLI connects to the hosted backend endpoint (no manual apiUrl setup required for end users).
• Endpoint override precedence is: AGON_API_URL (explicit runtime override), then AGON_HOSTED_API_URL, then AGON_API_HOSTNAME as https://<hostname>, then legacy fallback.
• After successful in-shell update, exit the shell and start agon again to run the newly installed runtime.
• On startup, Agon checks npm and alerts when a newer stable version is available.
• /attach accepts only a file path. Upload first, then send your message as a separate prompt.

Web Application (In Development)

Back to top

Browser-based interface with visual Truth Map explorer and real-time agent streaming. Coming soon.

iOS Application (In Development)

Back to top

Native iOS app for on-the-go strategy analysis. Coming soon.

Local Deployment (Developer Runbook)

Back to top

For local end-to-end testing, run the data services first, then the backend API, then your chosen client interface.

0) Build locally (repo root)

Back to top

cd /Users/simonholmes/Projects/Applications/Agon
dotnet build backend/Agon.sln
npm --prefix cli run build

1) Start required local data services (PostgreSQL + Redis + Azurite)

cd backend
docker compose up -d postgres redis azurite

Optional (DB admin UI):

cd backend
docker compose --profile tools up -d pgadmin

2) Configure local attachment storage (.env in repo root)

Create or update /Users/simonholmes/Projects/Applications/Agon/.env:

# Azurite local blob emulator (required for /attach)
BLOB_STORAGE_CONNECTION_STRING=UseDevelopmentStorage=true

Optional extraction settings for local dev:

# Disable cloud extraction dependencies for pure local testing
ATTACHMENTPROCESSING__DOCUMENTINTELLIGENCE__ENABLED=false
ATTACHMENTPROCESSING__OPENAIVISION__ENABLED=false

3) Run backend API locally

cd backend
dotnet run --project src/Agon.Api/Agon.Api.csproj

For local backend testing, point the CLI to your local API process:

AGON_API_URL=http://localhost:5000 npm exec -- agon

4) Run a local client

CLI (primary interface today, using local source build):

cd /Users/simonholmes/Projects/Applications/Agon
npm --prefix cli run build
AGON_API_URL=http://localhost:5000 node cli/bin/run.js

CLI (alternative, npm-exec from local package):

cd /Users/simonholmes/Projects/Applications/Agon/cli
npm install
AGON_API_URL=http://localhost:5000 npm exec -- agon

Optional auth token for secured API (JWT bearer):

AGON_AUTH_TOKEN="<jwt-token>" AGON_API_URL=http://localhost:5000 node cli/bin/run.js

Authentication: first-time setup

If the Agon backend is configured with Authentication:Enabled = true, a bearer token is required for all API calls. On first run without a token the shell will display an error and exit:

✗ Authentication required

The Agon backend at https://your-agon-host requires a bearer token.

First-time setup:
  agon login              Save your bearer token
  agon login --status     Check current auth status

Run agon login to save your token interactively:

agon login
# > Bearer token: ****

# Or non-interactively:
agon login --token "<your-bearer-token>"

The token is stored in ~/.agon/credentials with mode 0600 (owner read/write only). It is never stored in .agonrc so that the main config file can be safely committed to version control.

Additional agon login flags:

Flag	Description
--token <token>	Supply token directly (non-interactive)
--clear	Remove the stored token
--status	Show whether a token is configured and whether the backend requires one

Returning users: if you already set AGON_AUTH_TOKEN or AGON_BEARER_TOKEN as environment variables those continue to work unchanged. The environment variable takes precedence over a stored credentials file.

Web frontend (WIP):

cd frontend
npm install
npm run dev

Frontend default URL: http://localhost:3000

5) /attach local smoke test checklist

Run in CLI shell:

/new
/attach "./README.md"
/follow-up "Summarize this file in 3 bullets."

Expected:

• /attach returns upload success details (file name, content type, uploaded timestamp).
• /follow-up uses attachment context without 503 errors.
• /attach with trailing text (for example /attach ./README.md summarize this) is rejected with deterministic usage guidance.

6) Troubleshooting /attach

• 503 + ATTACHMENT_STORAGE_NOT_CONFIGURED:
  • BLOB_STORAGE_CONNECTION_STRING is missing/empty. Set it in repo-root .env, then restart backend.
• 503 + ATTACHMENT_STORAGE_UNAVAILABLE:
  • Azurite is down or not reachable. Check docker compose ps and restart azurite.
• 503 + ATTACHMENT_METADATA_NOT_CONFIGURED:
  • backend persistence wiring is missing in current runtime profile.
• 503 + ATTACHMENT_METADATA_UNAVAILABLE:
  • database path is unhealthy; verify PostgreSQL connectivity and backend logs.
• Attachment file not found from CLI:
  • verify local path exists and use quotes for spaces.

7) Stop local data services

cd backend
docker compose down

8) Run local tests (repo root)

cd /Users/simonholmes/Projects/Applications/Agon
DOTNET_CLI_HOME=/tmp dotnet test backend/Agon.sln --verbosity minimal
npm --prefix cli test

Worktree-Based Local Testing (Feature Branch)

Back to top

Use this flow when you want to test a feature branch in isolation without disturbing your current working tree. Steps 1–5 of the Local Deployment (Developer Runbook) still apply for starting/stopping data services and running the full test suite; this section covers only the worktree-specific setup.

Placeholders — replace these throughout:

Placeholder	Example
<name_of_feature_branch>	feature/my-new-feature
<name_of_worktree>	agon-my-new-feature

Step 1 — Start local dependencies (from the main repo)

# From the main repo's backend directory
cd backend
docker compose up -d postgres redis

Step 2 — Fetch the feature branch and create a worktree

Run these from the Agon repository root (not from inside any existing worktree):

git fetch origin <name_of_feature_branch>
git worktree add .worktrees/<name_of_worktree> <name_of_feature_branch>

Concrete example:

git fetch origin feature/my-new-feature
git worktree add .worktrees/agon-my-new-feature feature/my-new-feature

Step 3 — Run the backend from the worktree (Terminal 1)

Navigate to the worktree from the Agon repository root (the worktree was created at .worktrees/<name_of_worktree> in Step 2):

cd .worktrees/<name_of_worktree>/backend
dotnet run --project src/Agon.Api/Agon.Api.csproj

Concrete example:

cd .worktrees/agon-my-new-feature/backend
dotnet run --project src/Agon.Api/Agon.Api.csproj

Step 4 — Run the CLI from the worktree (Terminal 2)

cd .worktrees/<name_of_worktree>/cli
npm install
npm run build
AGON_API_URL=http://localhost:5000 node bin/run.js

Concrete example:

cd .worktrees/agon-my-new-feature/cli
npm install
npm run build
AGON_API_URL=http://localhost:5000 node bin/run.js

Step 5 — Clean up the worktree when done

# From the Agon repository root
git worktree remove .worktrees/<name_of_worktree>

---

Repository Structure

Back to top

Agon/
├── backend/              # .NET 9 backend
│   ├── src/
│   │   ├── Agon.Domain/              # Pure business logic
│   │   ├── Agon.Application/         # Orchestration & use-cases
│   │   ├── Agon.Infrastructure/      # Persistence, MAF, SignalR
│   │   └── Agon.Api/                 # REST + SignalR host
│   ├── tests/
│   │   ├── Agon.Domain.Tests/
│   │   ├── Agon.Application.Tests/
│   │   ├── Agon.Infrastructure.Tests/
│   │   └── Agon.Integration.Tests/
│   └── Agon.sln
│
├── cli/                  # TypeScript oclif CLI + interactive shell
│   ├── src/
│   │   ├── commands/                 # oclif commands (start, show, status, etc.)
│   │   ├── shell/                    # Interactive shell engine
│   │   ├── api/                      # Backend API client
│   │   ├── state/                    # Local session/config management
│   │   ├── ui/                       # Terminal UI components
│   │   └── utils/                    # Logger, formatters, error handling
│   ├── test/                         # Vitest unit tests
│   └── package.json
│
├── frontend/             # Next.js App Router frontend (scaffold/WIP)
│
└── .github/
    ├── workflows/        # CI + badge automation
    ├── scripts/          # Badge update script
    └── instructions/     # Architecture & coding rules

---

For Developers

Back to top

This section is for developers working on the Agon codebase.

For a full environment setup walkthrough, see the Developer Setup Guide.

Prerequisites

Back to top

• .NET 9.0 SDK (download)
• Node.js 20+ (download)
• PostgreSQL 16+ (for production; tests use in-memory DB)
• Redis 7+ (for production; tests use mocked client)

---

CLI (TypeScript)

Back to top

Architecture

Back to top

The CLI is built with oclif (Open CLI Framework) and provides both command-driven and interactive shell modes.

Key components:

• Commands (src/commands/) - oclif command classes for start, show, status, sessions, resume, config, answer
• Interactive Shell (src/shell/) - Full-featured REPL with slash commands, history, and streaming output
• API Client (src/api/) - REST client wrapper for backend communication with retry logic and error handling
• State Management (src/state/) - Local session cache and config management (~/.agon/)
• UI Components (src/ui/) - Terminal renderers for Markdown, progress indicators, and formatted output
• Utilities (src/utils/) - Logger, error formatter, session flow helpers

Running Tests

Back to top

cd cli
npm test

Test Coverage

Back to top

CLI test projects use Vitest. Coverage is tracked in cli/coverage/coverage-summary.json and included in the combined badge at the top of this README.

Key Technologies

Back to top

• oclif 3.0 - CLI framework with plugin architecture
• inquirer - Interactive prompts for clarification Q&A
• ora - Terminal spinners for async operations
• chalk - Terminal colors and styling
• marked-terminal - Markdown rendering in terminal
• axios - HTTP client for API communication
• Vitest - Unit testing framework

---

Backend (.NET)

Back to top

Architecture

Back to top

The backend follows Clean Architecture with strict layer separation:

┌─────────────────────────────────────┐
│         API Layer                    │  ← HTTP endpoints, middleware
│  ┌───────────────────────────────┐  │
│  │   Infrastructure Layer        │  │  ← Database, SignalR, MAF, Redis
│  │  ┌─────────────────────────┐  │  │
│  │  │  Application Layer      │  │  │  ← Orchestration, use-cases
│  │  │  ┌───────────────────┐  │  │  │
│  │  │  │  Domain Layer     │  │  │  │  ← Pure business logic
│  │  │  │                   │  │  │  │
│  │  │  └───────────────────┘  │  │  │
│  │  └─────────────────────────┘  │  │
│  └───────────────────────────────┘  │
└─────────────────────────────────────┘

Key principle: Dependencies point inward only. Domain has zero external dependencies.

Running Tests

Back to top

cd backend
dotnet test

Current status: See the Tests badge at the top of this README (auto-updated on main).

Test Coverage

Back to top

Coverage and aggregate test counts are maintained by CI badges at the top of this README.

Backend test projects:

• backend/tests/Agon.Domain.Tests
• backend/tests/Agon.Application.Tests
• backend/tests/Agon.Infrastructure.Tests
• backend/tests/Agon.Integration.Tests

Key Technologies

Back to top

• EF Core 9.0 with PostgreSQL provider (Npgsql)
• Microsoft Agent Framework (MAF) via Microsoft.Extensions.AI
• StackExchange.Redis 2.11.8 for snapshot storage
• SignalR for real-time UI updates
• xUnit + FluentAssertions + NSubstitute for testing

NuGet Packages

Back to top

# Domain (no external dependencies)
dotnet add src/Agon.Domain/Agon.Domain.csproj package <none>

# Application (interfaces only)
dotnet add src/Agon.Application/Agon.Application.csproj package Microsoft.Extensions.AI

# Infrastructure (all I/O)
dotnet add src/Agon.Infrastructure/Agon.Infrastructure.csproj package \
  Microsoft.EntityFrameworkCore \
  Npgsql.EntityFrameworkCore.PostgreSQL \
  StackExchange.Redis \
  Microsoft.AspNetCore.SignalR.Core \
  Microsoft.Extensions.AI.OpenAI \
  Anthropic.SDK

---

Frontend (Next.js)

Back to top

Tech Stack

Back to top

• Next.js 16 with App Router
• React 19
• TypeScript 5
• Tailwind CSS v4
• Current scope: scaffold/WIP (app/layout.tsx, app/page.tsx)

Getting Started

Back to top

cd frontend
npm install
npm run dev

Open http://localhost:3000 to see the app.

Current Project Structure

Back to top

frontend/
├── app/
│   ├── layout.tsx
│   ├── page.tsx
│   └── globals.css
│
├── public/
├── next.config.ts
└── package.json

Frontend Roadmap (Planned)

Back to top

• Thread View and Truth Map UI
• Real-time SignalR updates
• Session creation and follow-up UX
• Artifact browsing and export actions

---

Testing & Quality

Back to top

Test Coverage

Back to top

Coverage and test counts are maintained by CI badges at the top of this README. Badges are automatically refreshed on every push/merge to main by .github/workflows/update-badges.yaml.

Testing Strategy

Back to top

• Backend: TDD strict — tests written first, implementation follows
• Domain: Pure unit tests (no mocks, blazing fast)
• Application: Unit tests with mocked repositories
• Infrastructure: Integration tests with in-memory DB and mocked external services
• Frontend: UI tests are currently not part of required CI/merge gates for this phase

Running Tests

Back to top

Run the full test suite from the repository root:

# Backend (.NET)
dotnet test backend/Agon.sln --verbosity minimal

# CLI (TypeScript)
npm --prefix cli test

Individual project tests:

# Backend domain tests only
dotnet test backend/tests/Agon.Domain.Tests

# CLI tests with coverage
cd cli && npm run test:coverage

Pre-Merge Validation Protocol

Back to top

Use this exact checklist before merging PRs that touch CLI and backend behavior.

Important local-config note:

• cli/.agonrc is your local shell config (for example apiUrl, friction, research toggle).
• It is intentionally gitignored and should not be committed.
• You can still test locally with it; not committing it does not affect your local runs.

Track A — CLI behavior against deployed backend

1. Point CLI to deployed environment:

   agon
   /set apiUrl https://api-dev.agon-agents.org
   /params

2. Validate /update message clarity:

   /update --check
   /update

   Expected:
   • update result is shown
   • explicit instruction to exit and restart agon to use new runtime
3. Validate moderator routing (no unnecessary full debate):
   • Ask a short direct question: What is DNS?
   • Ask a short utility prompt without a question mark: Today's weather for AB31 5UQ
   • Run /status Expected:
   • direct answer from moderator
   • no transition into AnalysisRound for this short direct question
   • response is concise and does not expand into debate-style framework sections
4. Validate post-delivery assistant simplicity:
   • Complete one debate flow and then ask a simple follow-up: What do DNS record types do? Expected:
   • answer is direct and concise
   • no unnecessary template-style framing
5. Validate attachment image path:
   • Drag/drop or paste an image path into shell, then ask: Analyze this image. Expected:
   • if vision extraction is configured: answer references image content
   • if not configured: explicit warning about backend vision extraction configuration

Track B — backend fix validation locally

1. Start local dependencies and backend:

   cd backend
   docker compose up -d postgres redis azurite
   dotnet run --project src/Agon.Api/Agon.Api.csproj

2. In a second shell, point CLI to local backend and run checks:

   agon
   /set apiUrl http://localhost:5000
   /params

3. Run targeted automated tests before PR merge:

   # CLI tests
   npm --prefix cli test
   
   # Backend orchestration + extraction tests
   dotnet test backend/tests/Agon.Application.Tests/Agon.Application.Tests.csproj --filter "FullyQualifiedName~Orchestration"
   dotnet test backend/tests/Agon.Infrastructure.Tests/Agon.Infrastructure.Tests.csproj --filter "FullyQualifiedName~AttachmentTextExtractor"

4. Run full suite when changing shared flows:

   dotnet test backend/Agon.sln --verbosity minimal
   npm --prefix cli test

---

Local Pre-Commit Hooks

Back to top

Local pre-commit test gate is available at .githooks/pre-commit and runs:

• CLI tests
• Backend tests
• Changeset validation (if CLI code changed)

To enable local git hooks:

git config core.hooksPath .githooks

Changeset validation is enforced by default in local pre-commit hook when cli/ changes are staged.

---

CLI Release Process

Back to top

Workflows

Back to top

• CI checks: .github/workflows/ci.yaml
• Release + publish: .github/workflows/publish-cli.yaml

Manual Steps (Developer)

Back to top

1. In any PR that changes cli/, create a changeset:

   npx --yes @changesets/cli add --cwd cli
   # Choose patch, minor, or major

2. Merge the feature PR to main
3. Merge the auto-generated release PR (title: chore(release): version @agon_agents/cli)

Automated Steps (GitHub Actions)

Back to top

1. PR CI fails if cli/ changed without a cli/.changeset/*.md file
2. After merge to main, Changesets action:
   • Reads pending changesets
   • Creates/updates the release PR
   • Bumps cli/package.json and updates changelog
3. When release PR is merged, Changesets action publishes to npm (latest) using trusted publishing (OIDC)

Requirements

Back to top

• npm Trusted Publisher configured for this repository/workflow
• publish-cli.yaml has id-token: write permission
• Package passes npm run release:publish (tests + pack dry-run + publish)

---

Architecture Documentation

Back to top

Full architecture, round policy, agent roster, and coding guidelines are in .github/instructions/:

• architecture.instructions.md — System topology, runtime responsibilities, data model
• prd-agon-core.instructions.md — Product requirements, features, UX flows
• round-policy.instructions.md — Phase transitions, convergence rules, HITL policy
• copilot.instructions.md — Coding rules, TDD requirements, output templates
• schemas.instructions.md — JSON schemas for all data structures
• backend-implementation.instructions.md — MAF integration, solution structure, layer rules

---

Current Status (March 2026)

Back to top

✅ Completed

Back to top

• Backend API layer: Session/message/artifact endpoints are implemented in Agon.Api.
• Debate orchestration: Orchestrator + AgentRunner are active and tested.
• CLI shell: agon default interactive shell with slash commands and follow-up flow.
• Root .gitignore: Consolidated ignore patterns for monorepo.
• TDD discipline: backend + CLI test suites run in local hooks and CI.

🚧 In Progress

Back to top

• Frontend: Next.js UI iteration and backend integration.

📋 Next Steps

Back to top

1. Frontend:

   • Scaffold core layout (Thread View + Truth Map Drawer)
   • Implement SignalR client connection manager
   • Build session creation flow
   • Implement real-time agent token streaming

2. Integration:

   • Connect frontend to backend API
   • End-to-end testing with real LLM providers
   • Performance optimization (streaming latency, patch application)

3. CLI polish:

   • Continue shell UX refinements (formatting, streaming indicators, guidance text)
   • Expand command help and parameter controls
   • Harden long-running follow-up/debate visibility behavior

---

Contributing

Back to top

This project follows strict Clean Architecture and TDD principles. See .github/instructions/copilot.instructions.md for full coding guidelines.

Key Rules

Back to top

1. TDD is non-negotiable: Write tests first, then implementation (RED → GREEN → REFACTOR)
2. Clean Architecture layers: Domain has zero framework dependencies
3. No Docker required: All tests use in-memory databases or mocked clients
4. Structured logging: Use ILogger<T> (backend) or lib/logger.ts (frontend)
5. Error boundaries: Every route must have error.tsx and root must have global-error.tsx

Reporting Issues and Feature Requests

Back to top

If you encounter a bug or have a feature request, please open an issue and include:

• A clear, descriptive title
• Steps to reproduce the problem (for bugs)
• Expected and actual behaviour
• Your environment (OS, Node.js version, .NET version, CLI version)
• Any relevant log output (check ~/.agon/logs/agon.log for CLI logs)

For feature requests, describe the problem you are trying to solve and your proposed solution. The more context you provide, the easier it is for maintainers to evaluate and prioritise.

Submitting Pull Requests

Back to top

1. Fork the repository and create a feature branch from main.
2. Follow the TDD cycle: write a failing test first, then implement the fix or feature.
3. Ensure all existing tests continue to pass (dotnet test backend/Agon.sln and npm --prefix cli test).
4. If your change touches the CLI package, add a changeset before opening the PR:

   npx --yes @changesets/cli add --cwd cli

5. Keep pull requests focused — one logical change per PR makes review faster.
6. Fill out the PR description with a summary of what changed and why.
7. PRs that reduce test coverage below the current baseline will not be merged.

---

License

Back to top

Proprietary — All rights reserved.

---

Contact

Back to top

For questions or contributions, contact the development team.

---

Notes for Project Maintainers

Back to top

This section captures operational notes relevant to maintainers of the Agon repository.

Badge Maintenance

Back to top

CI badges at the top of this README are auto-updated by .github/workflows/update-badges.yaml on every push to main. If badge values appear stale, manually trigger the workflow from the Actions tab.

npm Publish

Back to top

The CLI package (@agon_agents/cli) is published to npm via GitHub Actions using OIDC trusted publishing. No npm token is stored in repository secrets — ensure the npm Trusted Publisher is configured for publish-cli.yaml with id-token: write permission before any release.

Dependency Updates

Back to top

Dependencies should be updated regularly:

# CLI
cd cli && npm outdated

# Backend
cd backend && dotnet list package --outdated

Run the full test suite after any dependency bump before merging.

Architecture Documentation

Back to top

All living architecture documents are in .github/instructions/. Update these files alongside code changes to keep them accurate. They are auto-injected into Copilot sessions, so stale documentation directly affects AI-assisted development quality.