Skip to content

AGENTS.md

Latest commit

 

History

History
469 lines (343 loc) · 15.5 KB

AGENTS.md

File metadata and controls

469 lines (343 loc) · 15.5 KB

🛠️ SIN-Code Tool Suite — IMMER UNSERE EIGENEN TOOLS NUTZEN (PRIORITY -10.0 - ABSOLUTE OBERSTE REGEL)

⚠️ ABSOLUTE REGEL: Niemals opencode-eigene Tools nutzen, wenn unsere SIN-Code Tools verfügbar sind!

UNSERE 7 SIN-Code Tools sind BESSER als die opencode-eigenen Alternativen. Jeder Agent MUSS unsere Tools nutzen, niemals die opencode-internen.

Wann welches Tool?

Aufgabe SIN-Code Tool (NUTZEN!) Opencode Alternative (NICHT nutzen!) Warum unsere besser
Dateien suchen, Projekt-Struktur erkunden sin-discover opencode interne Dateisuche Pattern-Matching, Relevanz-Scoring, Dependency-Map, Gruppierung
Befehle ausführen, Kommandos laufen lassen sin-execute opencode interne Shell-Ausführung Secret-Redaction, Safety-Checks, Timeout-Handling, Error-Analyse
Architektur analysieren, Module mappen sin-map opencode interne Code-Analyse Module-Level, Entry-Points, Hot-Paths, Dependency-Graph, Orphan-Detection
Einzelne Datei verstehen, Code analysieren sin-grasp opencode interne Code-Analyse Struktur, Dependencies, Usage, Context, Related-Files
Code durchsuchen, Patterns finden sin-scout opencode interne Suche Regex, Semantic, Symbol, Usage-Search, Dead-Code-Detection
URLs abrufen, APIs konsumieren sin-harvest opencode interne HTTP-Requests Caching, Struktur-Extraktion, Change-Detection, Auth-Management
Tasks managen, Planung, Rollback sin-orchestrate opencode interne Task-Planung Dependencies, Parallel-Execution, Blocker-Detection, Rollback-Plan

Tool-Verweisung & Skills/MCP

Tool MCP Name GitHub Repo Skill Installiert
sin-discover sin-discover OpenSIN-Code/SIN-Code-Discover-Tool sin-discover ✅ ~/.local/bin/discover
sin-execute sin-execute OpenSIN-Code/SIN-Code-Execute-Tool sin-execute ✅ ~/.local/bin/execute
sin-map sin-map OpenSIN-Code/SIN-Code-Map-Tool sin-map ✅ ~/.local/bin/map
sin-grasp sin-grasp OpenSIN-Code/SIN-Code-Grasp-Tool sin-grasp ✅ ~/.local/bin/grasp
sin-scout sin-scout OpenSIN-Code/SIN-Code-Scout-Tool sin-scout ✅ ~/.local/bin/scout
sin-harvest sin-harvest OpenSIN-Code/SIN-Code-Harvest-Tool sin-harvest ✅ ~/.local/bin/harvest
sin-orchestrate sin-orchestrate OpenSIN-Code/SIN-Code-Orchestrate-Tool sin-orchestrate ✅ ~/.local/bin/orchestrate
sin-websearch sin-websearch OpenSIN-Code/SIN-Code-Websearch-Skill sin-websearch ✅ ~/.config/opencode/skills/sin-websearch
sin-scheduler sin-scheduler OpenSIN-Code/SIN-Code-Scheduler-Skill sin-scheduler ✅ ~/.config/opencode/skills/sin-scheduler
sin-marketplace sin-marketplace OpenSIN-Code/SIN-Code-Marketplace-Skill sin-marketplace ✅ ~/.config/opencode/skills/sin-marketplace
sin-slash sin-slash OpenSIN-Code/SIN-Code-Slash-Skill sin-slash ✅ ~/.config/opencode/skills/sin-slash
sin-goal-mode sin-goal-mode OpenSIN-Code/SIN-Code-Goal-Mode-Skill sin-goal-mode ✅ ~/.config/opencode/skills/sin-goal-mode

Anwendungsbeispiele

1. Neues Projekt erkunden:

# NIEMALS opencode-interne Dateisuche nutzen!
/Users/jeremy/.local/bin/discover -path /Users/jeremy/dev/NEUES-PROJEKT -pattern "**/*.py" -sort_by relevance -format json
# Ergebnis: Alle Python-Dateien absteigend nach Relevanz sortiert, mit Dependencies und Related-Files

2. Befehle sicher ausführen:

# NIEMALS opencode-interne Shell-Ausführung nutzen!
/Users/jeremy/.local/bin/execute -command "npm test" -timeout 60 -format json
# Ergebnis: Safety-Check, Secret-Redaction, Error-Analyse, Timeout-Handling

3. Architektur verstehen:

# NIEMALS opencode-interne Code-Analyse nutzen!
/Users/jeremy/.local/bin/map -path /Users/jeremy/dev/PROJEKT -action map -format json
# Ergebnis: Module, Entry-Points, Hot-Paths, Dependency-Graph, Orphan-Detection, Complexity

4. Code durchsuchen:

# NIEMALS opencode-interne Suche nutzen!
/Users/jeremy/.local/bin/scout -query "func.*main" -path /Users/jeremy/dev/PROJEKT -search_type regex -format json
# Ergebnis: Alle Main-Funktionen, mit Usage-Count, Architecture-Info, Context

5. API/URL abrufen:

# NIEMALS opencode-interne HTTP-Requests nutzen!
/Users/jeremy/.local/bin/harvest -url "https://api.example.com/data" -format json
# Ergebnis: Status, Body, Headers, Struktur-Extraktion, Caching

6. Tasks planen & tracken:

# NIEMALS opencode-interne Task-Planung nutzen!
/Users/jeremy/.local/bin/orchestrate -action add -title "Feature implementieren" -tags "urgent" -format json
# Ergebnis: Task-ID, Dependencies, Parallel-Execution-Plan, Rollback-Plan

Regeln

  • SOFORTIGER PERMANENTER BAN bei Nutzung von opencode-internen Tools statt unserer SIN-Code Tools
  • VOR jedem Coding-Task: Erst mit sin-discover das Projekt erkunden, dann mit sin-grasp die relevante Datei verstehen
  • VOR jedem Refactoring: Erst mit sin-map die Architektur analysieren, dann mit sin-scout alle Referenzen finden
  • VOR jedem Befehl: Immer sin-execute mit Safety-Check und Secret-Redaction nutzen
  • VOR jedem API-Call: Immer sin-harvest mit Caching und Struktur-Extraktion nutzen
  • Für jede Planung: Immer sin-orchestrate mit Dependencies und Rollback-Plan nutzen

Versionen (aktuell)

Tool Version Status
sin-discover v0.2.5-fixes ✅ Stable
sin-execute v0.2.4-fixes ✅ Stable
sin-map v0.2.5-fixes ✅ Stable
sin-grasp v0.2.4-fixes ✅ Stable
sin-scout v0.1.5-fixes ✅ Stable
sin-harvest v0.1.4-fixes ✅ Stable
sin-orchestrate v0.1.6-fixes ✅ Stable

📚 CoDocs Standard — Code Documentation (PRIORITY -9.0)

Every meaningful code file needs two documentation layers:

  1. .doc.md companion — the "what and why" overview
  2. Inline # comments — the "how and why here" detail in the code itself

Both layers must exist. Neither replaces the other.

Layer 1: CoDocs (.doc.md companion)

Every code file gets a .doc.md companion file in the same directory.

Naming

router.py         → router.doc.md
config.yaml       → config.doc.md
api/types.ts      → api/types.doc.md
Makefile          → Makefile.doc.md

Code reference

First line of the code file:

# Docs: router.doc.md
// Docs: types.doc.md
# Docs: Makefile.doc.md

What belongs in a .doc.md

  • What does this file do? (1 sentence)
  • Which other files import / touch it? (dependency map)
  • Important config values & limits
  • Why certain decisions were made (e.g. "no async here because X")
  • Usage examples (1-2 lines)
  • Known caveats or footguns

What does NOT belong in a .doc.md

  • Implementation details (inline comments handle that)
  • Git history (that's what git log is for)

Layer 2: SOTA Inline Documentation

Every code file must also have professional inline #////#: comments. This is not about "comment every line" — it is about providing semantic context that an agent can't infer from the code alone.

SOTA Inline Doc Rules

1. File header (mandatory)

Every code file starts with:

# Purpose: <what this file does in 1 line>
# Docs: <companion .doc.md path>

For Python use """ module docstrings instead of #:

"""Handle user authentication.

Docs: auth.doc.md
"""

For TypeScript/Rust/etc use doc-comment style:

/**
 * Handle user authentication.
 * Docs: auth.doc.md
 */

2. Public API: docstrings (mandatory)

Every public function, method, class, type, and constant needs a docstring:

def calculate_route(
    origin: Coordinate,
    dest: Coordinate,
    traffic: bool = False,
) -> Route:
    """Shortest path between two coordinates.

    Uses A* with Manhattan heuristic. Raises if both coords
    are identical (avoids zero-length route).
    """
    ...
/** Shortest path between two coordinates.
 *
 * Uses A* with Manhattan heuristic. Throws if both coords
 * are identical (avoids zero-length route).
 */
function calculateRoute(
  origin: Coordinate,
  dest: Coordinate,
  traffic: boolean = false,
): Route { ... }

3. Non-obvious logic: inline context comments

Add a comment when the code does something surprising:

  • Why NOT the obvious approach: # not using dict comprehension because ...
  • Why this value: # 50ms timeout — must be < retry-after of upstream (60ms)
  • Why this ordering: # flush before close — close may skip unflushed data
  • Edge case: # handles None because protocol allows null fields
  • Performance note: # O(n²) but n ≤ 10 in practice
  • Security note: # sanitize_input() prevents SQL injection here

4. Section separators (recommended for 100+ line files)

# ── Auth ──────────────────────────────────────

Visually group related blocks. The long line makes sections scannable.

5. Magic values & config keys

Always explain:

MAX_RETRIES = 3    # upstream SLA guarantees < 2 failures per 1000
WAIT_SECONDS = 60  # must match upstream rate-limit window
const MAX_RETRIES = 3   // upstream SLA guarantees < 2 per 1000
const WAIT_SECONDS = 60 // must match upstream rate-limit window

6. Tests: describe scenario + expected behavior

def test_retry_exhaustion():
    """After 3 retries, route should raise UpstreamError."""

Test names plus docstrings = executable documentation.

7. Deprecation & migration markers

def old_login():  # DEPRECATED(v2): use authenticate() instead

When to update inline docs

  • Every change to a function's signature: update its docstring
  • Every change to non-obvious logic: add/update the context comment
  • Every new module: file header + section separators
  • Every new public API: docstring on add

When NOT to comment

  • i += 1 — obvious code needs no comment
  • x = 1 — unless 1 is a meaningful constant
  • Getter/setter boilerplate
  • Standard library calls with obvious semantics

Validation

After changes, verify with the bundle CLI:

sin codocs check            # exit 1 if any .doc.md reference is broken
sin codocs check --json     # machine-readable output
sin codocs list             # list every reference and whether it resolves

For inline docs, use manual review with:

# Check files that have NO module-level docstring/Purpose line
python3 -c "
import ast, sys
for f in sys.argv[1:]:
    try:
        tree = ast.parse(open(f).read())
        if not (isinstance(tree.body[0], ast.Expr) and hasattr(tree.body[0].value, 'value') and 'Purpose' in tree.body[0].value.s if hasattr(tree.body[0].value, 's') else isinstance(tree.body[0], ast.Expr) and isinstance(tree.body[0].value, ast.Constant)):
            print(f'MISSING PURPOSE: {f}')
    except: print(f'PARSE ERROR: {f}')
"

Exceptions

  • docs/ folder — architecture docs, ADRs, setup guides
  • README.md — project overview
  • No .doc.md for pure config files without logic (.gitignore, .prettierrc, etc.)
  • No inline docs required for throwaway scripts in debug/, tmp/, experimental branches

MarkItDown Integration (Microsoft)

Converts everything to Markdown for LLM consumption: PDF, DOCX, PPTX, XLSX, Images (OCR), Audio, HTML, CSV/JSON/XML, ZIP, YouTube, EPUB, Outlook MSG.

Installation

pipx install markitdown                          # recommended (CLI + library)
pip install 'markitdown[pdf, docx, pptx, xlsx]'  # minimal
pip install 'markitdown[all]'                    # everything

CLI

markitdown file.pdf > file.md                     # stdout
markitdown file.pdf -o file.md                    # output file
cat file.pdf | markitdown                         # pipe
markitdown --use-plugins file.pdf                 # with plugins (OCR)
markitdown file.pdf --use-cu --cu-endpoint "<e>"  # Azure Content Understanding

Python API

from markitdown import MarkItDown
md = MarkItDown()
result = md.convert("document.pdf")
print(result.text_content)

# With LLM vision (image descriptions in PPTX/Images)
from openai import OpenAI
md = MarkItDown(llm_client=OpenAI(), llm_model="gpt-4o")

# Security: local files only
result = md.convert_local("document.pdf")

CoDocs pipeline

for f in docs/*.pdf docs/*.docx docs/*.pptx; do
    markitdown "$f" -o "${f%.*}.doc.md"
done
# then add `# Docs: filename.doc.md` to the matching code file

Security

  • convert() runs with the calling process's full file-IO rights. Never pass untrusted input directly.
  • Prefer convert_local() / convert_stream() for controlled access.

Reference

https://github.com/microsoft/markitdown | pipx install markitdown

SIN-Code-Execute-Tool

Safe command execution with timeout, output capture, safety checks, and error analysis.

Quick Start

# Build and install
go build -o ~/.local/bin/execute ./cmd/execute

# Run a command
execute -command "echo hello" -format json

# With timeout
execute -command "sleep 5" -timeout 2 -format json

# Redact secrets
execute -command "echo API_KEY=secret123" -format json

Features

  • Safety checks: Blocks dangerous commands (rm -rf /, etc.)
  • Secret redaction: Automatically redacts API keys, tokens, passwords
  • Environment variable redaction: Redacts USER, HOME, etc.
  • Timeout handling: Kills processes after timeout, shows [TIMEOUT]
  • Error analysis: Analyzes exit codes and provides suggestions
  • Persistent history: Saves execution history to ~/.local/state/sinator/
  • Signal handling: Handles SIGKILL, SIGTERM, SIGINT, SIGSEGV

Links

Version

v0.2.4-fixes

SIN-Code-Bundle

Unified CLI and MCP server for the entire SIN-Code agent-engineering stack.

Quick Start

# Install
pip install -e .

# Show status
sin status

# Bootstrap repo
sin bootstrap .

# Run SIN-Code Go tool
sin sin-code run discover --path . -pattern "**/*.py" -format json

# Generate AGENTS.md
sin sin-code agents-md --output AGENTS.md

Features

  • Unified CLI: Single sin command for all tools
  • MCP server: Unified MCP server for all agents
  • Status detection: Auto-detects installed subsystems
  • Graceful degradation: Works with partial installations
  • Go tool integration: Runs SIN-Code Go tools via sin sin-code run
  • AGENTS.md generator: Generates tool suite documentation

Links

Version

v0.2.0