Skip to content

AGENTS.md

Latest commit

 

History

History
347 lines (282 loc) · 19.5 KB

AGENTS.md

File metadata and controls

347 lines (282 loc) · 19.5 KB
Raw

AGENTS.md — SIN-Code Master Blueprint

Single source of truth for ALL agents (human or AI) working on this repository. Read this file completely before making any change. If reality and this file diverge, fix the divergence in the same PR (code or doc — whichever is wrong).

Last verified against main: v3.28.0 (2026-06-30) — 10 new features (context meter, voice input, decision memory, TUI collapsible, background agents, spec-driven dev, session sharing, plugin system, MCP auto-install, LSP auto-configure) CEO Audit: Score 100, A+, 48/48 gates, 0 unapproved findings, 0 rot-risk. Test suite green and environment-independent.

1. What this repository IS

SIN-Code (formerly SIN-Code-Bundle) is the flagship product of the OpenSIN-Code organization: a verification-first, self-improving coding agent shipped as a single Go binary (sin-code), with a Python companion package (sin / sin serve).

It is simultaneously:

  1. A coding-agent CLI (sin-code chat, sin-code -p "...") — interactive REPL/TUI and headless one-shot mode, like Claude Code / Codex CLI, but with a mandatory correctness gate before any task is reported done.
  2. A unified MCP server (sin-code serve / sin-serve) — 52+ semantic tools consumable by ANY agent (Claude Code, Codex, opencode, our own loop, WebUI-v2).
  3. A multi-agent orchestrator — DAG dispatcher with critic, adversary, governor, episodic memory, confidence scoring, blame/impact analysis, cartographer.
  4. A bounded-autonomous system (v3.5.0) — goal queue, cron/file triggers, skill-lifecycle manager; the daemon runs goals end-to-end with hard safety invariants.

Unique selling point (never compromise this): every completed task MUST pass the verification gate (PoC proof or Oracle check) before the agent reports success. No other coding agent in the world enforces this.

MANDATORY SESSION START PROTOCOL (GLOBAL — EVERY SESSION)

This is a hard, non-negotiable rule for ALL agents (opencode, Claude Code, Codex, orca, sin-code, etc.) working in this ecosystem.

At the very beginning of EVERY session, before reading any code, planning work, or executing any other task, you MUST do the following in order:

  1. Execute understand-anything
    Fully understand the current project, workspace state, recent changes, open goals/tasks, relevant SKILL.md / AGENTS.md / CLAUDE.md, architecture, and context. Use every available tool, skill, and method (sin-context-bridge, git status/log, project docs, MCP tools, full context loading, etc.). Do not proceed until you have deep, up-to-date understanding.

  2. Execute skillopt
    Run the SkillOpt / SkillOpt-Sleep process (via the integrated skill, skillopt-sleep run, or equivalent CLI with real backend) to review recent agent sessions/transcripts for this project. This updates and optimizes the active skill document (SKILL.md or equivalent). Self-improvement is mandatory.

This protocol applies globally. Skipping it is a violation equivalent to breaking verification gates or other hard mandates.

2. What this repository is NOT

  • NOT a fork of opencode. OpenSIN-Code/OpenSIN-Code was an opencode fork and is ARCHIVED (Phase 1, 2026-06-12). Never copy code from it, never reference it as a dependency.
  • NOT related to Code-Swarm. That is a separate product, out of scope.
  • NOT a place to vendor tool implementations that live in their own repos (see ecosystem map, section 5).
  • NOT the WebUI. WebUI-v2 lives in its own repo (/Users/jeremy/dev/sin-code-web-ui-v2) and is wired via sin-code serve over stdio + @ai-sdk/mcp. The WebUI PR cycle is owned by a separate agent — never edit WebUI-v2 from this repo's agent loop.

3. Hard mandates (violations block merge)

M1 — CI/CD: n8n delegator ONLY

NEVER run build/test/lint on normal GitHub Actions runners. This org uses n8n + OpenSIN-AI/sin-github-action exclusively (webhook secret N8N_CI_WEBHOOK_URL); all real work executes on the OCI free-tier VM. The only permitted runs-on: ubuntu-latest job is the ~2s curl delegation step itself. Docs: docs.opensin.ai/best-practices/ci-cd-n8n

M2 — Single binary

sin-code ships as ONE static Go binary. CGO_ENABLED=0. SQLite via modernc.org/sqlite only. No runtime dependencies beyond the binary itself.

M3 — Verification gate is sacred

The agent loop must never report task success while verify_mode != "off" and the gate has not passed. Default verify_mode is "poc". The daemon refuses to start without --verify-cmd (autonomy requires a gate).

Stop-gate (loop engineering, decoupled completion authority): when a Definition-of-Done contract is present (internal/goalcontract), the worker's "done" is necessary but NOT sufficient. After the verify-gate passes, an independent stop-gate (internal/stopgate) confirms the contract — deterministic checks first (fail-closed: ANY failed check blocks, including predicates), then a strong/equal LLM judge (SIN_EVALUATOR_MODEL, fallback worker model) for non-mechanical criteria. A green judge can never override a red deterministic check. Rejection re-injects the open criteria and forces continued work. All of this is opt-in and fail-safe: nil stop-gate / empty contract / no contract flag preserves exact legacy single-gate behavior.

Tool coverage gate (issue #248): the runtime ToolCoverageEnforcer in internal/agentloop/ is part of the verification gate. When required_tools are configured and the model completes a run without invoking every required tool, or when a forbidden_tools entry was invoked, the loop rejects the completion and re-injects the violation as open criteria. The enforcer is fail-closed and race-safe (M7).

Daemon loop-engineering flags: --max-continuations (checkpoint+resume past --max-turns instead of aborting, bounded), --max-depth (sub-goal nesting via the spawn_subgoal tool), --no-contract (disable Definition-of-Done, revert to single verify-gate). Discovery: goal discover [--dry-run] and the discover trigger type turn TODO/FIXME markers and MASTER_TODO.md items into deduplicated goals. Env vars: SIN_EVALUATOR_MODEL, SIN_EVALUATOR_BASE_URL, SIN_EVALUATOR_API_KEY.

Headless sandbox mandate (issue #420): every sin-code chat -p, sin-code chat --json, and sin-code daemon invocation routes sin_bash through sandbox.Command (landlock on Linux, seatbelt on macOS, bubblewrap where available). The OS-level isolation is on by default — there is no turn-off flag that survives audit. --no-sandbox exists on chat as an explicit, WARN-emitting escape hatch for debugging; the daemon has no such opt-out (it is headless by mandate). A bare sh -c fallback in sin_bash is reserved for non-headless REPL mode only when the operator opts out and never for headless / autonomous runs.

M4 — Permission engine gates everything destructive

Every tool call goes through the permission engine (allow / ask / deny). In headless mode, ask resolves to deny unless --yolo is passed. The daemon is always headless — it cannot self-escalate permissions.

Headless-mode sandbox baseline (issue #420): the permission engine gates which tools the LLM may call; the sandbox baseline (M3 above) crates what those tools can do at the OS level. In headless mode (-p, --json, daemon) the two layers stack — M4 denies a destructive tool that the operator would have refused interactively, and the sandbox confines any tool M4 did approve to the workspace roots. A second sh -c exit in sin_bash is treated as a defect — see the audit table in §10 of CHANGELOG.md for the remaining operator-controlled sh -c paths (verify-cmd, hooks.json command hooks, *.spec.md verify: directives).

v3.9.0 bridge additions (default policies, see cmd/sin-code/internal/permission_defaults.go):

Tool pattern Policy Layer Reason
vane__* allow research (Bridged-External) read-only citations, sandboxed
superpowers__* allow methodology (obra) already local, just registered
dox__* allow context (agent0ai) protocol check, read-only
gh_query allow contributing (Bridged-External) read-only: issue/pr/release/workflow-run/repo
gh_health allow contributing (Bridged-External) PATH + auth probe, no side effects
gh_execute ask contributing (Bridged-External) mutating ops require human confirmation (M4)
fusion__tournament ask autonomy (Fusion) spawns sub-agents, costs money
fusion__status allow autonomy (Fusion) read-only tournament status
fusion__config allow autonomy (Fusion) read-only config query
notion__notion_read_* allow productivity (Bridged-External) read-only Notion: workspaces, pages, databases, blocks, comments, users
notion__notion_write_* ask productivity (Bridged-External) mutating Notion: create/update/archive pages, append/delete blocks, comments
notion__notion_raw_cli ask productivity (Bridged-External) raw CLI escape hatch — arbitrary subcommands (M4)

M5 — Module path

github.com/OpenSIN-Code/SIN-Code (since v3.0.0). The old path .../SIN-Code-Bundle must not appear in any new code, config, or doc.

M6 — SIN tools over naive built-ins

The tool router always prefers semantic SIN tools over naive equivalents: sin_edit over string-replace, SCKG navigation over blind file reads, EFM environments over ad-hoc mocks.

M7 — Race-free concurrency

The orchestrator and any goroutine-using subsystem MUST be verified under go test -race before merge. The 2026-06-12 v3.0.0 migration surfaced three real races in internal/orchestrator/dispatcher.go; treat any unguarded shared-field mutation as a merge blocker.

M8 — context7 + web search before coding (MANDATORY)

NEVER write code that uses a library, framework, SDK, or API without first consulting context7 for up-to-date documentation. This is a hard gate — agents that skip this step produce code with hallucinated APIs, stale signatures, and deprecated patterns.

The mandatory pre-code sequence is:

  1. context7__resolve-library-id → identify the library
  2. context7__query-docs → fetch current docs for the specific API/topic
  3. sin_web_search → supplement with real-world usage examples, edge cases, and community knowledge that docs may not cover
  4. THEN write code

Exceptions (narrow): pure logic with no external dependencies, standard library only, or the user explicitly says "just code it" / "no docs needed". When in doubt, always look it up. The cost of a 2-second docs query is negligible compared to the cost of shipping broken code.

The skill-multimodal-web-tools skill (v3.28.0+) documents the full 5-layer tool inventory and decision tree. context7 is Layer 5 and is marked as required_tools in the skill frontmatter.

🏆 CEO-AUDIT PFLICHT — SOTA Repository Review (PRIORITY -10.0)

ABSOLUTE REGEL: Vor jedem Release, Refactoring, "ist es SOTA?" oder Production-Deployment MUSS die ceo-audit Skill genutzt werden. Sie ist die kritische Ergänzung zu den SIN-Code Tools: Board-Grade, 47-Gate, 8-Achsen Review.

Trigger → Profil: "audit this"/"check SOTA"/"board review" → FULL (47 Gates); "production-ready?"/"before I release" → RELEASE; "is this secure?"/"pen-test?" → SECURITY (12 Gates).

sin ceo-audit install                         # einmalig
sin ceo-audit run /path/to/repo --profile=FULL
sin ceo-audit run /path/to/repo --profile=SECURITY
sin ceo-audit run /path/to/repo --profile=RELEASE
sin ceo-audit run /path/to/repo --grade=B     # CI-Mode: exit code = grade gate

8 Achsen (47 Gates): Security 12, Performance 6, Code-Quality 7, Testing 5, Dependencies 5, Documentation 4, Architecture 4, Compliance 4. Output: report.{md,sarif,html,json} unter ~/ceo-audits/<repo>-*/. Voll-Detail (Grading-Scale, alle Trigger, Formate): siehe docs/agents/ceo-audit.md.

5. Ecosystem map (org-level, fixed)

See ECOSYSTEM.md for the complete inventory with integration status and sync rules. Single-line summary:

Layer Repos Integration
Agent + Tool plane SIN-Code (this repo) The product
Web frontend SIN-Code-WebUI-v2 (/Users/jeremy/dev/sin-code-web-ui-v2) Spawns sin-code serve; follows releases
Multi-agent fan-out SIN-Code-Orchestration External MCP server
Verification & analysis (issue #28) SCKG-Tool, IBD-Tool, PoC-Tool, ADW-Tool, EFM-Tool, Oracle-Tool, Symfony-Lens CLI subprocess + MCP
Code intelligence Simone-MCP External MCP server (AST/LSP)
Browser automation SIN-Browser-Tools External MCP server (106 tools)
Skills (12) websearch, scheduler, goalmode, grillme, marketplace, codocs, contextbridge, honcho, frontend, mcpbuilder, browser, simone External MCP servers (registry.go)
LLM backends SIN-Code-FireworksAI-OpenCode-Config Agent profiles (profiles/*.toml)
Distribution homebrew-sin goreleaser pushes formula sin-code
Infra Infra-SIN-OpenCode-Stack Deployment
Archived — never use OpenSIN-Code, SIN-Code-Bundle-Web, 6 long-name duplicates, coder-SIN-Qwen Do not reference
Out of scope Code-Swarm Separate product

Referenz-Sektionen (ausgelagert — Token-Ersparnis)

Diese Detailkapitel sind aus AGENTS.md ausgelagert. Bei Bedarf gezielt lesen (cat docs/agents/<datei> bzw. via rtk), nicht standardmäßig in den Kontext ziehen:

Thema Datei Wann lesen
Architektur (v3.5.0) + State-Machine docs/agents/architecture.md Bevor du den Agent-Loop / Orchestrator anfasst
Repository-Layout (95 Pakete) docs/agents/repo-layout.md Wenn du eine Datei/ein Paket suchst
Configuration Contract (alle Keys) docs/agents/config-contract.md Bevor du Config/Flags/DB-Pfade änderst
Roadmap v3.0.0–v3.28.0 docs/agents/roadmap.md Für Versions-/Feature-Historie
Naming & Stability Rules docs/agents/naming-stability.md Bevor du Tools/Skills/CLI umbenennst (Breaking-Change-Policy)
Evaluation & Observability (#75) docs/agents/eval-observability.md Für Eval-Pipeline / OTel-Tracing
CEO-Audit Voll-Detail docs/agents/ceo-audit.md Grading-Scale, alle Trigger/Formate

SIN-Code CLI — aktiv aufrufen (Effizienz-Tools, kein MCP-Bloat)

Diese Tools laufen als CLI (0 Schema-Tokens im Kontext). Proaktiv nutzen — sie sind billige Signale, die kaputten Code vor dem Commit verhindern:

Situation Kommando Warum
Vor Refactor/Löschen eines geteilten Symbols sin review Intent + Risiko statt Zeilen-Diff eyeballen
Vor Merge / „done" markieren sin verify Unabhängige, ausführungsbasierte Verifikation — nie self-reported „grün" trauen
Code-Gesundheit vor großen Änderungen sin debt Architektur-Schulden-Score prüfen
Coding-Workflow-Hub (scaffold/preflight) sin code Zugang zu allen sin-Coding-Schritten
Paralleles Code-Suchen scout / map / grasp Semantische Suche/Architektur/Datei-Verständnis statt blindem Grep
Env-Setup je Repo (idempotent) sin bootstrap Subsysteme für ein Repo initialisieren

Regeln: (1) sin verify vor jedem „done" — grüner Compile ist kein Beweis. (2) sin review statt Roh-Diff bei eigenen Änderungen. (3) Ist ein Tool nicht verfügbar: sag es explizit und mach graceful weiter. Voll-Übersicht: sin --help.

graphify — Code-Graph statt blind grep (LLM-frei, ~25x weniger Tokens)

Vor breiter Code-Exploration den Wissensgraphen fragen statt Dateien zu lesen. Der Graph wird deterministisch per tree-sitter gebaut (0 LLM-Kosten) und nach jedem Commit auto-aktualisiert (.planning/config.json → graphify aktiv):

  • graphify query "<frage>" — scoped Subgraph für eine Frage (BFS über graph.json)
  • graphify path "A" "B" — wie hängen zwei Symbole zusammen
  • graphify explain "X" — Symbol + Nachbarn in Klartext
  • graphify update . — Graph neu extrahieren (LLM-frei, nur geänderte Dateien)

Regel: Bei „wo ist X / was ruft Y / Blast-Radius" erst graphify query, nicht 20 Dateien grep’en. Kein Graph vorhanden? graphify update ., dann fragen.

9. Development workflow

  • Go 1.26+. Before EVERY commit: go build ./... && go test ./... -race -count=1. The full suite is now green and environment-independent: Docker-dependent tests auto-skip when the daemon is unavailable; orchestrator, autonomy, security, and harvest tests no longer depend on ambient environment or timing.
  • Conventional commits (feat:, fix:, docs:, feat!: for breaking).
  • Releases: tag push vX.Y.Z ⇒ goreleaser builds multi-arch + updates brew.
  • Never reduce test count or coverage. New loop code targets ≥80% coverage.
  • Python side (src/sin_code_bundle): ruff + pytest, same PR discipline.
  • Docs: every behavioral change updates docs/ + CHANGELOG.md in the same PR.
  • AGENTS.md + ECOSYSTEM.md are kept in sync with the codebase (CI ecosystem-sync.yml enforces registry↔permission↔ECOSYSTEM agreement).
  • File-mode policy (SIN_CODE_FILE_MODE): write paths that would otherwise hard-code 0o644 go through cmd/sin-code/internal/filemode.Default(). Operators can dial the mode down (e.g. 0o600) for security-sensitive deployments by setting SIN_CODE_FILE_MODE to a valid octal string (0o600 or 0600 form). The knob refuses group/other-write modes that would loosen the 0o644 baseline. Close-to-source exceptions stay tight: internal/update_manifest.go writes the install manifest at 0o600 and internal/index_store.go creates the index dir at 0o750.

11. For external AI agents (Claude Code, Codex, etc.) working here

  1. Read sections 3 (mandates) and 8 (roadmap) before any edit.
  2. Use the repo's own tools on itself when available (sin-code serve dogfooding).
  3. One C-gap or one issue per PR. No drive-by refactors.
  4. If you cannot satisfy a mandate, STOP and report — do not work around it.
  5. WebUI-v2 is OUT OF SCOPE for this repo's agent loop. Edits to /Users/jeremy/dev/sin-code-web-ui-v2 belong to that repo's local agent.

11.1 Known runtime DB locations

The Go binary writes SQLite DBs to user-config directories by default (issue #265 / #62). Workspace isolation is keyed by a 12-char sha256 of the workspace's absolute path so two projects never share a row.

Purpose Path (relative to os.UserConfigDir()/sin-code/) Module Issue
Lessons log workspaces/<sha256-prefix12(abs(ws))>/lessons.db internal/tui/dbhome.go + agent_runner.go #265
Session store workspaces/<sha256-prefix12(abs(ws))>/sessions.db internal/tui/dbhome.go + agent_runner.go #265
Code index <root>/.sin-code/index.bin (per-project, intentional) internal/index_store.go n/a

internal/session/store.go:DefaultPath() and internal/lessons/store.go:DefaultPath() keep their ~/.local/share/sin-code/ shape for direct CLI use (sin-code sessions without a workspace). The TUI agent runner resolves the home through Config.DBHome (overridable in tests; default = os.UserConfigDir()).

These files are NOT inside the workspace tree and so cannot be accidentally git add-ed. The legacy .gitignore rule (lines 64–65) remains as a defence-in-depth for users who keep a pre-migration working tree. Migration to add automatic move-from-old-path is out of scope for issue #265.