aixcl

Imported from xencon/aixcl (AGENTS.md). Install upstream with npx skills add xencon/aixcl. Copyright stays with the author.

AGENTS.md

Authoritative agent operating contract for this repository.

0. Cold Start -- Read These First

If you are starting a new session in this repository, read exactly these four documents in this order and stop:

You do NOT need to read .claude/rules/ or .opencode/rules/ separately -- they are subsets of the above and loaded automatically by your tool. You do NOT need to read .opencode/agents/agent-context.md -- it carries only OpenCode-agent-specific operational guidance (work queue, tool list, memory) and defers to this file for all policy.

After reading those four files you are fully oriented. Begin work.

Git Remote Configuration (Fork Workflow)

This repository uses a two-remote fork workflow. Understand this before any git push:

Push branches to origin, open PRs against upstream.

git push origin issue-<N>/<description>
gh pr create --repo xencon/aixcl ...

If the upstream remote is missing: git remote add upstream git@github.com:xencon/aixcl.git

Never push directly to upstream/main or upstream/dev. Use SSH (not HTTPS) for all remotes -- HTTPS will be blocked by workflow file protection.

1. Core Principles

1. Security over convenience
2. Determinism over creativity
3. Minimal scope changes
4. Explicit reasoning over implicit assumptions
5. No speculative modifications

2. Authority Hierarchy

When conflicts arise, follow this order:

1. Direct human instruction in active session
2. This AGENTS.md file (operating contract)
3. DEVELOPMENT.md (workflow rules, templates)
4. .opencode/rules/ and .claude/rules/ (behavioral constraints)
5. docs/architecture/governance/ (platform invariants)
6. docs/developer/ (developer guides)

3. Critical Constraints

Issue-First Development (MANDATORY)

ALWAYS create an issue before starting work. No exceptions without explicit override.

• Title: [TYPE] Description (NO colons)
• Labels: component:* required
• Assignee: Required
• Branch: issue-<number>/<short-description> from dev
• Commit: <type>: <description> (under 72 chars), include Fixes #<number>
• PR: <description> (#<number>) (NO colons), assignee + labels at creation time

For complete details:

• docs/developer/development-workflow.md -- Full step-by-step guide
• DEVELOPMENT.md -- Quick reference and PR race condition rules

Platform Invariants (NON-NEGOTIABLE)

Fixed Core Runtime

• Inference Engine (Ollama) - Docker-managed, always enabled
• Never remove, replace, or conditionally disable the Inference Engine

Supported AI Coding Clients (Non-Exclusive)

AIXCL is client-agnostic above the OpenAI-compatible API layer. OpenCode and Claude Code are documented clients; other MCP-compatible or OpenAI-API-compatible tools are equally valid. Do not treat any specific AI coding client as a platform invariant.

Runtime vs Operational Services Boundary

• Runtime core must be runnable without operational services
• Runtime core must never depend on operational services
• Network mode: host networking for all services (by design)

Formatting Rules

• NO colons in issue/PR titles (e.g. [TASK] Setup agent, not [TASK]: Setup agent)
• NO Unicode checkmarks: Use - [x] checkboxes, not emoji
• ASCII only: Plain text for cross-platform compatibility
• Unix line endings (LF), never CRLF (.gitattributes enforces LF; CI fails on CRLF)

Label Taxonomy

Issue Types: Bug, Feature, Task

Component Labels (required): component:runtime-core, component:ollama, component:persistence, component:observability, component:ui, component:cli, component:infrastructure, component:testing

Other Labels:

• Priority: P1, P2, P3
• Profile: profile:bld, profile:sys
• Category: Fix, Enhancement, Refactor, Maintenance
• Agent delegation: agent (issues delegated to a peer agent -- e.g. the OpenCode agent -- for execution; the agent discovers delegated work by listing open issues with this label)
• Security: security (security-relevant issues and PRs: capability hardening, secret handling, permission fixes, vulnerability follow-ups)

Lean Repository Policy

• Delete outdated reports and dated documentation; do not archive
• Operations reports should be current (within 30 days)
• Generated files stay generated; use .gitignore
• Verify: no dated reports, no tracked generated files, no stale archive directories

4. Safe Areas for Agentic Contribution

You MAY:

• Modify operational services (monitoring, logging, automation)
• Improve documentation
• Adjust CLI ergonomics (without changing semantics)
• Organize Compose files (if invariants preserved)
• Add new operational profiles or tooling

You MUST NOT:

• Remove/replace/disable runtime core components
• Introduce runtime core -> operational service dependencies
• Merge runtime logic with monitoring/admin tooling
• Collapse service boundaries
• Add external libraries, cloud services, telemetry, or analytics without explicit approval

5. Essential Commands

./aixcl is the single entry point for both runtime and developer workflow.

Stack Operations

./aixcl utils check-env               # Validate environment prerequisites
./aixcl stack start --profile sys     # Start stack
./aixcl stack status                  # Check service health
./aixcl stack stop                    # Stop all services gracefully

Validation, Tests, and Release

./aixcl checks all                    # Full local CI parity sweep (summary table)
./aixcl checks agents                 # Mirror parity only (.claude/.opencode)
./aixcl test all                      # Run every test suite
./aixcl test lib                      # Shell library unit tests (no stack needed)
./aixcl release status                # Where the current release cycle stands

6. Self-Verification Checklist

Before ANY operation, confirm:

• I have read AGENTS.md and DEVELOPMENT.md
• This change is explicitly requested and minimally scoped
• Sufficient repository evidence exists (no hallucination risk)
• Required issue exists or override is documented per Section 8
• No security principles are violated
• No unauthorized dependencies are introduced
• Merged files scanned for conflict markers (when merge performed)
• Staged diff reviewed before commit -- no unexplained mass deletions, no placeholder/elision text standing in for preserved content (verify: ./scripts/checks/check-ai-elisions.sh --staged)

If ANY check fails -> HALT and escalate.

Definition of Done

A task is complete only when ALL of the following are true:

• All CI checks are green (not just locally passing)
• ./scripts/checks/check-ai-elisions.sh --staged ran clean before commit
• PR is approved and merged to dev
• Linked issue is closed
• No broken relative links introduced (run bash scripts/checks/check-paths.sh)

7. Escalation Procedures

When halting due to insufficient evidence, missing requirements, or conflicts:

1. If working on an issue: Post clarification question as issue comment
2. If no issue exists: Ask human operator directly; do not create issue unilaterally
3. If security concern: Flag with [SECURITY] prefix and await explicit approval
4. If authority conflict: Document override request, obtain explicit written confirmation

8. Emergency Workflow Override

In exceptional situations, a human operator may explicitly authorize the agent to proceed without a pre-existing issue.

Required: Direct instruction: "[OVERRIDE] Proceed without creating an issue first."

Conditions:

• Override applies ONLY to the specific change
• All OTHER rules still apply (branch naming, commits, GPG signing, PRs, CI)
• The change must be minimal and reversible

Retroactive Documentation: Create a [TASK] issue prefixed with [OVERRIDE] after completion.

Commit Format: [OVERRIDE] type: Brief description

Does NOT qualify: "just do it" without context, or vague urgency.

9. Human in the Loop Checklist Policy

The agent MUST distinguish between agent-completed items and human-verification items.

The human sees [ ] on verification items and ticks them during code review.

9.5 Agent Identification in GitHub Interactions

Every comment or PR body posted by an agent to GitHub MUST end with a standard identification block. This lets reviewers calibrate trust based on which agent, model, methodology, and scope produced the contribution.

Required block format

Use plain ASCII only. Place the block at the end of the comment or PR body, after any substantive content:

---
- Agent: <agent name and model>
- Date: YYYY-MM-DD
- Method: <what the agent did, e.g. read-only repository scan>
- Scope: <files, issues, or context the agent had access to>
- Confirmation: <whether any code changes were made; yes/no>
---

Field meanings: Agent = YOUR OWN tool name and model (never copy an example's identity); Date = posting date (YYYY-MM-DD); Method = what the agent did (e.g. read-only repository scan); Scope = files, issues, or context the agent had access to; Confirmation = yes if code or file changes were made, no if read-only.

Required on: every agent-authored issue body, issue comment, PR description, and PR review comment. Not required on: commit messages (conventional format takes precedence), internal tool output, human-authored content.

10. Quick References

Per-Directory Documentation

• CONTEXT.md -- agent-facing directory contract: what the directory contains, what agents MAY and MUST NOT do there. Read it before editing files in a directory that has one.
• README.md -- human-facing overview; used at the repository root and top-level directories only (config/, lib/, scripts/, tests/, docs/).
• Not every directory has a CONTEXT.md. Absence means no constraints beyond this contract apply -- read the code.
• docs/README.md is the complete index of docs/; update it in the same PR that adds, moves, or removes a doc.

Tool Usage

• Prefer actually running commands over printing them
• Avoid destructive operations (git push --force, git reset --hard)
• Load files on a need-to-know basis (lazy loading)
• Preserve existing code style and conventions

Response Style

• Use plain ASCII text (no Unicode special characters)
• Prefer tabular formatting for commands, file lists, and status reports
• Be concise but thorough; surface risks explicitly
• Suggest tests when making code changes

11. External References

• DEVELOPMENT.md -- Full workflow rules and templates
• docs/developer/development-workflow.md -- Complete developer guide
• docs/architecture/governance/00_invariants.md -- Platform invariants
• docs/architecture/governance/01_ai_guidance.md -- Agentic behavioral guidance
• .opencode/rules/workflow.md -- OpenCode workflow constraints
• .claude/rules/workflow.md -- Claude Code workflow constraints
• .claude/rules/discussions.md / .opencode/rules/discussions.md -- GitHub Discussions policy (secret handling, untrusted-input treatment, advisory-only status)
• opencode.json -- OpenCode configuration

Remember: Security over convenience. Determinism over creativity. Minimal scope changes.