otherness — Projekt-Agenten-Kontext
Was das ist
otherness ist ein autonomes Softwareentwicklungssystem. Eine einzelne Sitzung übernimmt die Rollen von Koordinator, Entwickler, QA, Scrum Master und Produktmanager – nacheinander, in einer Schleife, ohne menschliches Eingreifen. Es arbeitet auf jedem auf GitHub gehosteten Projekt, indem es AGENTS.md, docs/aide/ und .otherness/state.json liest und dann autonom Aufgabenwarteschlangen generiert, Funktionen implementiert, PRs überprüft und Releases erstellt.
otherness läuft jetzt auf sich selbst. Wenn dieser Agent otherness verbessert, werden diese Verbesserungen bei der nächsten Ausführung über den Selbstaktualisierungsmechanismus (git -C ~/.otherness pull) auf alle Projekte, die otherness verwenden, bereitgestellt.
Status: Aktiv. Kernschleife stabil. Selbstverbesserungsmodus aktiviert.
⚠️ GLOBALER BEREITSTELLUNGSWARNUNG — VOR JEDEM MERGE LESEN
Änderungen an agents/standalone.md oder agents/bounded-standalone.md werden sofort auf jedes Projekt, das weltweit otherness verwendet, bei dessen nächstem Sitzungsstart bereitgestellt. Diese Dateien sind die änderungsreichsten und riskantesten. Siehe §Risikostufen für Änderungen unten.
SDLC-Prozess
Der Teamprozess ist in ~/.otherness/agents/standalone.md eingebettet. Diese Datei enthält nur projektspezifischen Kontext.
Projektkonfiguration
PROJECT_NAME: otherness
CLI_BINARY: ""
PR_LABEL: otherness
REPORT_ISSUE: 741
REPORT_URL: https://github.com/pnz1990/otherness/issues/741
BOARD_URL: ""
BUILD_COMMAND: bash scripts/validate.sh
TEST_COMMAND: bash scripts/test.sh
LINT_COMMAND: bash scripts/lint.sh
VULN_COMMAND: ""
Architektur
otherness ist eine Sammlung von Markdown-Anweisungsdateien, die von OpenCode (der KI-Coding-Agent-Laufzeitumgebung) gelesen werden. Es gibt keine kompilierte Binärdatei, keinen Server, keine Datenbank. Das „Produkt“ ist die Qualität der autonomen Agentenschleife, die diese Anweisungen erzeugen.
Bereitstellungsmodell: ~/.otherness/agents/ ist ein Git-Repository. Jeder Agent aktualisiert sich selbst über git -C ~/.otherness pull beim Start. Ein gemergter PR zu pnz1990/otherness:main wird beim nächsten Start für alle Benutzer bereitgestellt.
Laufzeitabhängigkeiten: OpenCode (führt die Agenten aus), gh CLI (gesamte GitHub-Interaktion), git (VCS + Worktree-Isolation + Selbstaktualisierung), python3 Standardbibliothek (YAML-Parsing, JSON-Zustand).
Zustand: .otherness/state.json auf einem dedizierten _state-Branch. Niemals auf main. Parallele Sitzungen verwenden Branch-Push als verteilte Sperre.
Skills: agents/skills/*.md – wiederverwendbare Checklisten, die von den Entwicklungs- und QA-Phasen geladen werden. Wachsend durch /otherness.learn.
Paketstruktur
~/.otherness/ ← Repository-Stamm (git clone an diesem Pfad)
agents/
standalone.md ← Schlanker Orchestrator: Zustandsverwaltung, Start, Schleifengerüst, harte Regeln
bounded-standalone.md ← Umfangreduzierter Agent – 50 Zeilen, die standalone.md umschließen
onboard.md ← Onboarding für bestehende Projekte
otherness.learn.md ← Lern-Agent – Wissen aus Open Source internalisieren
otherness.arch-audit.md ← Architekturprüfungs-Agent
gh-features.md ← GitHub-API-Referenz
phases/ ← Phasenimplementierungen (geladen von standalone.md)
coord.md ← Phase 1: Heartbeat, Ratelimit, Warteschlangengenerierungssperre, Überwachung, Claim
eng.md ← Phase 2: Spezifikation/Plan/Aufgaben (Speckit-Integration), Implementierung, Gedächtnis
qa.md ← Phase 3: Konfrontative Überprüfung, Spezifikationskonformität, Merge, Archivierung
sm.md ← Phase 4: Triage, Wiederherstellung nach Stagnation, Metriken, projektübergreifendes Lernen
pm.md ← Phase 5: Produktvalidierung, Roadmap-Gesundheit, Wettbewerbscheck
skills/ ← Wiederverwendbare Skill-Dateien
declaring-designs.md ← Spezifikationsqualitätsstandard
reconciling-implementations.md ← QA-Checkliste
agent-coding-discipline.md ← Chirurgische Änderungen, überprüfbare Ziele
autonomous-workflow-patterns.md ← Workflow-Entwurfsmuster
architectural-audit.md ← Vier-Linsen-Prüfungsmethodik
contribution-hygiene.md ← PR- und Commit-Disziplin
agent-responsibility.md ← Urteils- und Verantwortungsmuster
role-based-agent-identity.md ← Rollenidentitätsmuster
ephemeral-pr-artifacts.md ← PR-Operationsmuster
explicit-anti-patterns.md ← Anti-Pattern-Dokumentation
triage-discipline.md ← SM-Triage-Prozess
PROVENANCE.md ← Lern-Sitzungs-Prüfpfad
README.md ← Skill-Index
boundaries/
README.md
example.boundary
docs/
aide/
vision.md
roadmap.md
definition-of-done.md
progress.md
.otherness/
state.json ← nur auf _state-Branch
.opencode/
command/
otherness.run.md
otherness.run.bounded.md
otherness.setup.md
otherness.status.md
otherness.upgrade.md
otherness.learn.md
otherness.arch-audit.md
otherness.cross-agent-monitor.md
otherness-config.yaml
otherness-config-template.yaml
AGENTS.md
README.md
onboarding-new-project.md
onboarding-existing-project.md
scripts/
validate.sh ← BUILD_COMMAND-Ziel
test.sh ← TEST_COMMAND-Ziel
lint.sh ← LINT_COMMAND-Ziel
Risikostufen für Änderungen
Dies ist der wichtigste Abschnitt. Jeder PR muss vor dem Merge klassifiziert werden.
| Stufe | Dateien | Risiko | Merge-Gate |
|---|---|---|---|
| KRITISCH | agents/standalone.md, agents/bounded-standalone.md, agents/phases/*.md | Wird SOFORT auf ALLE Projekte ausgerollt. Eine kaputte Anweisung kann die nächste Sitzung jedes otherness-Benutzers zum Stillstand bringen. | [MENSCH NOTWENDIG] Überprüfung vor dem Merge erforderlich. Kein autonomer Merge. |
| HOCH | agents/onboard.md, agents/otherness.learn.md, otherness-config-template.yaml, onboarding-*.md | Betrifft die Einrichtung neuer Projekte oder die Lernschleife. | QA muss gegen das Referenzprojekt überprüfen. Autonomer Merge erlaubt, wenn Tests bestehen. |
| MITTEL | agents/skills/*.md, agents/gh-features.md, boundaries/ | Zusätzliches Wissen. Regressionen haben geringe Auswirkungen. | Standard-QA-Zyklus. Autonomer Merge. |
| NIEDRIG | docs/, README.md, AGENTS.md, scripts/ | Dokumentation und Grundgerüst. Keine Laufzeitauswirkungen. | Autonomer Merge. |
KRITISCHE Stufenregel: Jeder PR, der agents/standalone.md, agents/bounded-standalone.md oder agents/phases/*.md betrifft, muss [MENSCH NOTWENDIG: kritische-stufen-änderung] im PR posten und NICHT autonom gemergt werden. Für die menschliche Überprüfung belassen.
Was „Tests“ für otherness bedeuten
otherness hat keine Komponententests. Seine Korrektheit kann nur validiert werden, indem man es auf einem echten Projekt ausführt und das Verhalten beobachtet.
scripts/validate.sh (BUILD_COMMAND) führt diese strukturellen Prüfungen durch:
- Keine festcodierten Projektpfade – Agenten-, Phasen- und Skill-Dateien dürfen in ausführbarem Anweisungskontext keine bestimmten Projekte referenzieren. PROVENANCE.md und HTML-Kommentar-Provenienz-Metadaten sind ausgenommen.
- Skill-Referenzen sind auflösbar – jede
Skill laden: lies ...-Referenz instandalone.mdundagents/phases/*.mdzeigt auf eine vorhandene Datei auf der Festplatte oder im Repository. - Erforderliche Dateien vorhanden – alle Agenten-, Phasen-, Skill-, Dokumentations- und Befehlsdateien, die im erforderlichen Satz aufgeführt sind, sind vorhanden.
- Selbstaktualisierung vorhanden –
standalone.mdenthält dengit -C ~/.otherness pull-Selbstaktualisierungsblock.
scripts/test.sh (TEST_COMMAND) führt alle 4 Validierungsprüfungen plus durch:
- Integrationstest – überprüft, ob otherness korrekt auf dem Referenzprojekt läuft (erster Nicht-otherness-Eintrag in
monitor.projectsinotherness-config.yaml), indem geprüft wird, ob der_state-Branch Aktivität innerhalb der letzten 72 Stunden zeigt.
scripts/lint.sh (LINT_COMMAND) prüft Agentendateien auf strukturelle Korrektheit mit python3 (keine externen Tools erforderlich): CRLF-Zeilenenden, Nullbytes, erforderliche Phasenüberschriften in standalone.md.
Die Selbstverbesserungsschleife
Wenn otherness auf sich selbst läuft, sind die Verbesserungsbereiche:
- Agentenschleifenqualität – trifft der alleinstehende Agent bessere Entscheidungen? Messgröße: weniger
[MENSCH NOTWENDIG]-Eskalationen pro Stapel auf Referenzprojekten, kürzere Zeit bis zum Merge pro Element. - Skill-Tiefe – wachsen die Skill-Dateien durch
/otherness.learn-Sitzungen? Messgröße: PROVENANCE.md-Einträge, Anzahl der Skill-Dateien. - Onboarding-Reibung – produziert
/otherness.onboardvollständige, korrektedocs/aide/-Dateien? Messgröße: Wie viele manuelle Bearbeitungen sind nach dem Onboarding erforderlich. - Dokumentationsgenauigkeit – stimmt
README.mdmit dem tatsächlichen Verhalten überein? Messgröße: PM-Validierungsreise besteht. - Tooling – erkennen
scripts/validate.sh,scripts/test.sh,scripts/lint.shechte Regressionen? Messgröße: Diese Skripte verbessern sich im Laufe der Zeit.
Die PM-Phase muss otherness mit der Community, aus der es stammt (Hermes, Multica, Archon), pro Stapel vergleichen und Lücken identifizieren, die es zu schließen gilt.
Anti-Patterns (QA blockiert PRs, die diese enthalten)
| Pattern | Erkannt durch |
|---|---|
Mergen eines KRITISCHEN PRs ohne [MENSCH NOTWENDIG]-Label | QA – harter Block |
Festcodieren projektspezifischer Pfade in standalone.md (z.B. Flottenprojektnamen, Owner/Repo-Slugs) | QA |
| Agentenanweisung, die auf fehlende optionale Datei blockiert, ohne eleganten Fallback | QA |
| Skill-Datei, die auf Tools verweist, die nicht in jeder OpenCode-Sitzung verfügbar sind | QA |
Entfernen oder Schwächen des Selbstaktualisierungs-git pull beim Start | QA – harter Block |
Ändern des Schreibmusters des _state-Branches, ohne die Sicherheit paralleler Sitzungen zu überprüfen | QA – harter Block |
Aufgabe [x] ohne Implementierung | QA |
Label-Taxonomie
| Gruppe | Labels |
|---|---|
| Art | kind/enhancement, kind/bug, kind/chore, kind/docs |
| Bereich | area/agent-loop, area/skills, area/onboarding, area/tooling, area/docs |
| Priorität | priority/critical, priority/high, priority/medium, priority/low |
| Größe | size/xs, size/s, size/m, size/l, size/xl |
| Risiko | risk/critical, risk/high, risk/medium, risk/low |
| Typ | epic |
| Workflow | otherness, needs-human, blocked |
Produktvalidierungsszenarien (PM-Phase)
Der PM-Agent validiert otherness, indem er es auf Referenzprojekten beobachtet.
Das Referenzprojekt ist der erste Nicht-otherness-Eintrag in otherness-config.yaml
unter monitor.projects. Befehle unten verwenden $REFERENCE_PROJECT als Platzhalter –
ersetzen Sie ihn durch Ihren tatsächlichen Projekt-Slug (z.B. owner/my-project).
Szenario 1: Referenzprojekt ist aktiv
REFERENCE_PROJECT=$(python3 -c "
import re
in_monitor=in_projects=False
for line in open('otherness-config.yaml'):
if re.match(r'^monitor:',line): in_monitor=True
if in_monitor and re.match(r'\s+projects:',line): in_projects=True
if in_projects:
m=re.match(r'\s+- (.+)',line)
if m:
r=m.group(1).strip()
if not r.endswith('/otherness'): print(r); break
")
gh api "repos/$REFERENCE_PROJECT/branches/_state" \
--jq '.commit.commit.committer.date'
# Muss innerhalb von 72 Stunden liegen. Wenn älter: otherness ist auf dem Referenzprojekt zum Stillstand gekommen.
Bestanden: _state zeigt Commits innerhalb von 72 Stunden.
Szenario 2: Referenzprojekt hat offene PRs oder kürzliche Merges
gh pr list --repo $REFERENCE_PROJECT --json number,title,state,createdAt \
--jq '.[] | "\(.state) \(.createdAt) \(.title)"' | head -5
Bestanden: mindestens ein PR in den letzten 7 Tagen geöffnet oder gemergt.
Szenario 3: Skills wachsen
ls ~/.otherness/agents/skills/ | wc -l
# Muss ≥ 4 sein (die 4, mit denen wir gestartet sind). Wachstum bedeutet, dass /otherness.learn lief.
tail -20 ~/.otherness/agents/skills/PROVENANCE.md
Bestanden: PROVENANCE.md hat mindestens einen Eintrag, der innerhalb der letzten 30 Tage datiert ist.
Szenario 4: README stimmt mit tatsächlichem Verhalten überein
Lesen Sie README.md und gleichen Sie es mit agents/standalone.md ab.
Prüfung: Jeder in README aufgeführte Befehl existiert in .opencode/command/.
Prüfung: Jede im Stack-Diagramm aufgeführte Agentendatei existiert auf der Festplatte.
Öffnen Sie für jede gefundene Abweichung ein kind/docs-Issue.
Szenario 5: Selbstverbesserung findet statt
OTHERNESS_REPO=$(python3 -c "
import re
for line in open('otherness-config.yaml'):
m=re.match(r'^\s+repo:\s*(.+)',line)
if m: print(m.group(1).strip()); break
")
gh pr list --repo $OTHERNESS_REPO --state merged \
--json mergedAt,title --jq '.[] | "\(.mergedAt) \(.title)"' | head -10
Bestanden: mindestens ein PR in den letzten 14 Tagen gemergt. Wenn null:Kotherness hat sich in letzter Zeit nicht selbst verbessert. Untersuchen Sie die Ursache und öffnen Sie ein Issue.
Dateien, die Agenten nicht ändern dürfen
AGENTS.md(diese Datei)docs/aide/vision.mddocs/aide/roadmap.mdotherness-config-template.yaml(Änderungsrisikostufe HOCH – nur QA, nicht autonom)
Zukünftiges Risiko: Globales Bereitstellungsmodell
Dokument für zukünftige Betrachtung (Option B):
Derzeit wird jeder gemergte PR zum otherness-Hauptbranch sofort auf jedes Projekt, das otherness verwendet, über git -C ~/.otherness pull bereitgestellt. Dies ist Option A – schnell, einfach, keine Versionsverwaltung.
Das Risiko: Ein Fehler in agents/standalone.md legt gleichzeitig jede otherness-Sitzung überall lahm. Derzeit gemindert durch: KRITISCHE Stufe erfordert menschliche Überprüfung, Integrationstest auf dem Referenzprojekt und die Tatsache, dass die Agentenschleife widerstandsfähig ist (eine schlechte Anweisung führt zu einem [MENSCH NOTWENDIG] und nicht zu einem Absturz).
Wann auf Option B (versionierte Releases) upgraden:
- Wenn otherness von >10 verschiedenen Repos verwendet wird
- Wenn eine Regression auf KRITISCHER Stufe einen realen Schaden an einem Nicht-Test-Projekt verursacht hat
- Wenn Benutzer Stabilitätsgarantien über Sitzungen hinweg benötigen
Design von Option B: Git-Tags als Releases, Projekte pinnen auf einen Tag in otherness-config.yaml, /otherness.upgrade erhöht die Pin mit einem Changelog-Überprüfungsschritt. Die git pull-Selbstaktualisierung wird zu git checkout <gepinnte-tag>.