AGENTS.md · agentlas-ai/Agentlas-OS

Sections

1. Repository Constitution: Local Main Only
2. Public Release Allowlist (Hard Rule)
3. Source Of Truth
4. Third-Party Plugin Boundary
5. Generated Instruction Language
6. Source Code & Commit Language
7. Operating Loop
8. Hephaestus Network Commands
9. Team Roles
10. Output Contract
11. Mode Rules
12. Memory Preflight
13. Safety Rules

First lines (shown under the repo's Apache-2.0 license)

# Agentlas Core Engine Meta-Agent Team

<!-- AGENTLAS-INSTALL-ENTRY -->
> **Asked to install this repo, not to work on it?** This file is the
> contributor constitution and will not help you. Read the install block at the
> top of [README.md](README.md): it points at
> `scripts/install-all-runtimes.sh`, which writes only under `~/.agentlas`,
> `~/.local/bin`, and this host's own plugin/command-adapter directories.


## Repository Constitution: Local Main Only

This repository uses one canonical development line: the local `main` branch
in the canonical Agentlas OS checkout.

- Make every source change and commit directly on local `main`.
- Do not create feature, release, backup, agent-named, or temporary branches.
- Do not create Git worktrees. Use an external recovery directory or a verified
  Git bundle when a safety snapshot is required.
- Before editing, confirm the canonical checkout is on `main`, inspect status,
  fetch remote refs, and inspect `main...origin/main`. A GUI "Pull origin"
  button is not permission to pull or merge blindly.
- If local `main` is dirty, preserve it with a reviewed checkpoint commit before
  reconciling remote changes on that same branch.
- Push only `main` and intentional release tags. Do not publish side branches.

## Public Release Allowlist (Hard Rule)

Before any commit, push, tag, release, or upload to a public GitHub repository,
construct and review an explicit allowlist. Public source and release artifacts
may contain only files required for an end user to install and run the product,
plus public-facing `README`, `LICENSE`, and `CHANGELOG` material.

Never publish internal design or research documents, plans, benchmarks,
benchmark prompts or results, tests, fixtures, test data, scores, logs,
screenshots, signing material, certificates, credentials, environment files,
operator notes, private paths, local memory, or recovery artifacts. Run tests
and benchmarks only in local/private temporary storage or private CI; publish
neither their inputs nor their artifacts. Existing unrelated local work must
remain unstaged.

For a public release, do not use a blanket `git add -A`. Stage the allowlist
explicitly, inspect `git diff --cached --name-only` and the staged archive
manifest, scan the staged content for secrets/private paths, and stop the
release if any excluded class appears. A passing test does not authorize
publishing the test.

This repository is a portable four-agent meta-agent team. Use it to create or
package Agentlas-compatible single agents and multi-agent teams for Codex,
Claude Code, Antigravity, Cursor, OpenCode, OpenClaw, Hermes
Agent, Ollama-served local models (Gemma, DeepSeek — see
`docs/local-models.md`), and `AGENTS.md`-compatible runtimes.

## Source Of Truth

Maintainer documentation and source-verification scripts in this reference
index belong to the development checkout. Installed engines use the shipped
contracts, schemas, skills, and runtime entrypoints; missing maintainer notes
do not require downloading private source material.

- Canonical entry point: `AGENTS.md`.
- Architecture ownership rule: `docs/source-of-truth.md`.
- Runtime split and sync boundary: `docs/runtime-sync-boundaries.md`.
- Third-party plugin contribution boundary: `CONTRIBUTING.md` and
  `PLUGIN_CONTRIBUTIONS.md`.
- Global command contract: `docs/global-command-contract.md`.
- Production Ontology Runtime: `docs/ontology-runtime.md`, `ontology/`,
  `bin/ontology`, and `scripts/verify-ontology-runtime.sh`.
- Agentlas Cloud runtime contract: `docs/agentlas-cloud-runtime.md`,
  `agentlas_cloud/`, `schemas/agentlas-manifest.schema.json`, and
  `templates/agentlas.json.tpl`.
- Hephaestus Network 2.0 contract: `docs/hephaestus-network-2.0.md`,
  `docs/runtime-fallback-adapters.md`, `agentlas_cloud/networking/`,
  `schemas/routing-card.schema.json`, `.agentlas/routing-card.json`, and
  `scripts/verify-routing-cards.sh`.
- Stormbreaker robust execution contract: `docs/robustness-protocol.md`,
  `docs/robustness-eval.md`, and `schemas/robustness-eval-result.schema.json`.
- Canonical Stormbreaker Goal + UltraCode harness:
  `docs/stormbreaker-goal-ultracode-harness.md`,
  `agentlas_cloud/networking/stormbreaker_harness.py`, and
  `schemas/stormbreaker-goal-ultracode-harness.schema.json`.
- Builder quality gate: `contracts/builder-interview-research-gate.md`,
  `docs/builder-quality-research-basis.md`,
  `templates/builder-interview.md.tpl`, `templates/research-sources.md.tpl`,
  `templates/tool-selection.md.tpl`, `templates/domain-expert-synthesis.md.tpl`,
  `templates/prompt-performance-contract.md.tpl`, and
  `templates/capability-eval-plan.json.tpl`.
- Portable support contracts: `docs/mode-classifier.md`,
  `docs/clarify-question-loop.md`, `docs/agentlas-auto-activation.md`,
  `docs/local-credential-store.md`, and `docs/skill-lifecycle-promotion.md`.
- Agent experience and MCP contracts: `docs/agent-experience-assets.md`,
  `docs/mcp-build-resolution.md`, the matching `schemas/*.schema.json`
  files, `.agentlas/mcp-policy.json`, and
  `scripts/verify-experience-assets-contract.sh`.
- Team members: `agents/10-single-agent-builder/agent.md`,
  `agents/20-multi-agent-team-builder/agent.md`, and
  `agents/30-agentlas-packager/agent.md`, plus
  `agents/40-session-agent-builder/agent.md`.
- Mode contracts: `modes/single-agent-creator.md`, `modes/team-builder.md`,
  `modes/agentlas-packager.md`, and `modes/session-agent-builder.md`.
- Portable runtime core: `.agents/agentlas-core-engine-meta-agent/agent.md`.
- Reusable skills: `.agents/skills/*/SKILL.md` and root `skills/*/SKILL.md`.
- Agentlas contracts: `.agentlas/mode-map.json`,
  `.agentlas/agent-card.json`, `.agentlas/company-blueprint.json`,
  `.agentlas/sitemap.json`, `.agentlas/global-commands.json`,
  `.agentlas/memory-map.json`,
  `.agentlas/memory-tickets.jsonl`, `.agentlas/vault-references.json`,
  `.agentlas/local-credentials.map.json`, `.agentlas/mcp-policy.json`, and skill
  lifecycle files emitted in generated packages.
- Public install surfaces: `codex/`, `.claude/`, `antigravity/`, and
  `scripts/`.

Runtime-specific folders are adapters. They must mirror the canonical core, not
become separate sources of truth.

Agent Ontology (AO), Agent Workforce Ontology, the local semantic ontology,
Context Map, and Career Graph are independent active systems. Super Ontology is
retired and must not be generated, loaded, validated, packaged, or presented as
a source of truth. Its retained documentation is an archived design record only.

## Third-Party Plugin Boundary

Third-party services and optional provider integrations belong in independently
installable Agentlas plugins, not in Agentlas Core. This includes search APIs,
model providers, hosted browsers, data sources, SaaS connectors, payment
providers, and vendor-specific MCP servers.

Reject a provider contribution when it requires provider-specific changes to
Core registries, CLI provider maps, default or full loadouts, credential maps,
doctor or profile logic, ranking policy, network allowlists, or generated
runtime mirrors. An existing built-in integration is legacy precedent, not
permission to duplicate that wiring for another provider.

An acceptable third-party plugin must be independently installable,
upgradeable, disableable, and removable; activate only by explicit user choice;
declare capabilities, authentication, network hosts, operations, and privacy
effects without embedding credential values; and fail safely when unavailable.
Installing or removing it must not require a Core patch.

Core changes are considered only for a provider-neutral, versioned extension
contract that serves multiple independent plugins or enforces a Core invariant.
Propose that contract separately from any vendor implementation. Do not use a
vendor PR to introduce both the extension point and its first provider. Follow
`PLUGIN_CONTRIBUTIONS.md` for the submission and review checklist.

## Generated Instruction Language

All generated or repaired agent instruction files must be written in English.
This includes `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `agent.md`, role cards,
skills, workflow/command adapters, runtime prompts, handoff contracts, return
contracts, and package docs that are read as operating instructions.

Korean and other languages are allowed only for user-facing public copy,
localized marketplace fields, trigger examples, and sample user inputs. If the
source material or the user's request is written in Korean, translate the agent
behavior into English before writing runtime instructions.

## Source Code & Commit Language

This is a public, open-source repository. Code comments and commit messages