workspace-bootstrap

Ein OpenCode-Skill zum Aufsetzen neuer Multi-Repo-Workspaces mit Meta-Repo, Sibling-Repos, Agent-Konfiguration, Validierungs-Skripten und dem vollstaendigen Learning Feedback Loop.

Was der Skill macht

Der Skill workspace-bootstrap setzt ein neues Workspace nach einem bewaehrten Muster auf: ein Meta-Repo orchestriert mehrere eigenstaendige Sibling-Repos, jedes mit eigenem Git, eigenem docs/ai/-Baum und eigener Agent-Konfiguration. Das Vorbild ist wecouple_projekt/wecouple/ (Multi-Repo-Orchestrierung mit Meta-Repo, workspace.yml, workspace_check.sh) kombiniert mit nak-hopper-game/docs/ (docs-Dichte + vollstaendiger Learning Feedback Loop).

Er ist vollautomatisch: Er fragt den Nutzer ab (Interview-Phase), plant, implementiert, validiert und dokumentiert das gesamte Workspace in einem durchgaengigen Workflow. Das Ergebnis ist ein vollstaendiges, agent-freundliches Workspace mit docs/ai/-Baeumen pro Subprojekt, workspace_check.sh als Qualitaetsgate, und allen Artefakten des Learning Loop (Plan, Retrospektive, Explanation).

Das Setup ist reproduzierbar: Statt jedes neue Projekt von Hand zu scaffolden, liefert der Skill ein geprueftes, getestetes Muster, das an die konkreten Anforderungen (Siblings, Lizenzen, MCPs, Asset-Repos, Content-QA-Checkliste) angepasst wird.

Wann der Skill triggert

Der Skill feuert bei folgenden Trigger-Phrasen:

Deutsch:

• "neues Projekt aufsetzen"
• "workspace einrichten"
• "analog zu <projekt>"
• "neuen Workspace anlegen"
• "Projekt-Struktur erstellen"
• "Agent-freundliches Projekt aufsetzen"

Englisch:

• "set up a new project"
• "create a workspace"
• "bootstrap a workspace"
• "multi-repo setup"
• "scaffold a new project"

Auch implizit: wenn der Nutzer ein neues Projekt mit mehreren Subprojekten beschreibt, ohne explizit "workspace" zu sagen.

Wie der Skill funktioniert — der Workflow

Der Skill implementiert den vollstaendigen Learning Feedback Loop:

1. Interview-Phase — 16 Fragen (Workspace-Name, Parent-Dir, Siblings, Vorbildprojekte, Tool-Stack, Lizenzen, MCPs, Asset-Repo, Naming-Collision, Projekttyp + Content-QA-Checkliste, Security-Risiko-Signale + Security-Checkliste, Projekt-Standards, Skills/MCPs, Existing-Repos, Pattern-Typ). Der Projekttyp steuert Test-Runner und QA-Checkliste (docs/ai/validation.md); die Risiko-Signale steuern die Security-Checkliste (docs/ai/security.md) und die <PROJECT_SECURITY_BASH_ALLOW>-Scanner im security-review-Subagent.
2. Phase A: Meta-Repo-Skeleton + Setup-Plan — Meta-Repo anlegen (.opencode/, 10 Agenten, AGENTS.md, workspace.yml, docs/ai/-Baum, docs/issues/<workspace-name>-setup/ mit plan.md, scripts/workspace_check.sh + workspace_status.sh).
3. Testing-Strategy Integration — Aus dem Projekttyp (Frage 11) die passende QA-Checkliste aus references/testing-strategy-templates.md holen, <QA_CHECKLIST> in docs/ai/validation.md füllen, <PROJECT_SPECIFIC_BASH_ALLOW> in den Subagenten setzen. Bei other oder nicht treffendem Typ: websearch nach aktuellen Best Practices, Custom-Template bauen, Nutzer-Freigabe einholen.
4. Security-Review Integration — Aus dem Projekttyp (Frage 11) + Risiko-Signalen (Frage 12) die passende Security-Checkliste aus references/security-review-templates.md holen, <SECURITY_CHECKLIST> in docs/ai/security.md (neue Datei) füllen, <PROJECT_SECURITY_BASH_ALLOW> im neuen security-review.md-Subagenten setzen. Bei other oder Custom: websearch nach aktuellen Security-Best-Practices, Custom-Template, Nutzer-Freigabe. Der security-review-Subagent wird IMMER gebootet — er ist ein fester Workflow-Schritt, nicht optional.
5. Blind-Spot-Review — Plan von review-plan-blindspots auf uebersehene Risiken pruefen lassen, alle kritischen/mittleren Hinweise einarbeiten.
6. Nutzer-Freigabe — Plan + offene Fragen dem Nutzer vorlegen, auf Antworten warten.
7. Phase B: Sibling-Repos — Pro Sibling: git init, AGENTS.md nach Template, vollstaendiger docs/ai/-Baum, docs/issues/ (SDD issue-zentriert), docs/product/ + docs/technical/ falls zutreffend, README, LICENSE, .gitignore, ggf. .gitattributes + license-tracking.md fuer Asset-Repos. Danach Meta-Repo-Updates (workspace.yml is_git_repo, workspace_status.sh Pfadfix, workspace_check.sh Skeleton-Constraint, opencode.json MCP-Block, orchestrator.md Projekt-Standards, validation.md Content-QA-Checkliste, project-context, changelog, README). WICHTIG: bei 4+ Siblings in mehrere Subagent-Laeufe aufteilen (max ~2 neue Repos pro Lauf).
8. Validate — Nur Struktur-Checks: ./scripts/workspace_check.sh muss PASS (exit 0), workspace_status.sh alle Repos exists=yes + git=yes, alle Repos clean, bash -n, python3 -m json.tool. KEINE funktionalen Tests — die macht Schritt 9 (Test).
9. Test — test-feature-Subagent läuft IMMER (fester Schritt, symmetrisch zu security-review). Liest docs/ai/validation.md, führt Lint/Typecheck + Unit/Integration/E2E-Tests aus. Bei reinen Docs/Config-Änderungen: [skip: diff touches no code]. Fehlende Tests für neue Funktionen werden als [fail: no tests for X] reportet — implement-change muss sie schreiben. FAIL blockiert den Workflow (vor security-review). Subagent reportet nur, schreibt keine Tests.
10. Security-Review — security-review-Subagent läuft IMMER (fester Schritt). Liest docs/ai/security.md, führt universelle Baseline (gitleaks, semgrep, SCA) + projekttypspezifische Checks aus. Kritische Findings blockieren den Workflow — zurück zu implement-change. Keine DAST-Scans gegen Production (nur Staging).
11. Review-Diff — Diffs auf Bugs, fehlende Doku, Broken Links, Inkonsistenzen pruefen. Findings beheben.
12. Update-Docs — project-context, changelog, known-issues, fixes aktualisieren.
13. Retrospect — Lessons Learned, Follow-ups, Unsicherheiten in docs/issues/<task-id>/retrospective.md.
14. Explain-Location — Wo, was, wie im Workspace zu finden, in docs/issues/<task-id>/explanation.md.

Skill-Struktur

workspace-bootstrap/
├── SKILL.md                    (215 Zeilen, Haupt-Workflow-Guide)
├── README.md                   (diese Datei)
└── references/
    ├── meta-repo-structure.md  (Meta-Repo Dateibaum + Content-Templates)
    ├── sibling-template.md     (Sibling AGENTS.md + docs/ai/ + docs/issues/ Templates)
    ├── workspace-scripts.md    (workspace_check.sh + workspace_status.sh Templates)
    ├── agent-templates.md      (10 Agenten .md Templates mit permission:-Frontmatter)
    ├── plan-template.md        (Setup-Plan Struktur-Template)
    ├── testing-strategy-templates.md  (Projekttyp-spezifische QA-Checklisten + Test-Runner)
    ├── security-review-templates.md   (Projekttyp-spezifische Security-Checklisten + Scanner)
    └── review-log.md                  (Review-Log: bestätigte Konfigurationen + Fundings mit Quellen)

Datei-Erlaeuterungen:

• SKILL.md — Hauptanweisung, wird geladen wenn der Skill triggert. Enthaelt Interview-Fragen, Workflow-Schritte, Critical Rules.
• references/meta-repo-structure.md — Vollstaendiger Meta-Repo-Dateibaum mit Content-Templates fuer jede Datei. Wird in Phase A gelesen.
• references/sibling-template.md — Sibling-Repo-Template (AGENTS.md, docs/ai/-Baum, docs/issues/, README, LICENSE, .gitignore, .gitattributes, license-tracking.md). Wird in Phase B gelesen.
• references/workspace-scripts.md — Generische Templates fuer workspace_check.sh + workspace_status.sh (mit YAML-Parser, Fallback-Manifest, resolve_path-Fix, Skeleton-Constraint). Wird in Phase A gelesen.
• references/agent-templates.md — 10 Agenten-Templates (orchestrator + 9 Subagents) mit Frontmatter (mode, model, steps, permissions). Wird in Phase A gelesen.
• references/plan-template.md — Setup-Plan Struktur-Template mit allen Abschnitten (Ziel, Phasen A-D, Risiken, Validierung, Doku, Entscheide, Blind-Spot-Review-Ergebnisse). Wird in Phase A gelesen.
• references/testing-strategy-templates.md — Projekttyp-spezifische QA-Checklisten, Test-Pyramide, Tools, Runner-Kommandos und Subagent-Instruktionen pro Typ (game-godot, game-unity, game-unreal, video-content, web-app, mobile-app, api-backend, data-science, cli-tool, docs-content, other-custom). Wird in Phase A nach der Projekttyp-Antwort gelesen; bei other per websearch Custom-Template gebaut.
• references/security-review-templates.md — Projekttyp-spezifische Security-Checklisten, Scanner, Runner-Kommandos und Subagent-Instruktionen pro Typ (gleiche Typen wie testing-strategy), plus eine universelle Baseline (gitleaks + semgrep + SCA + Lizenz-Compliance) und eine Risiko-Rubric (welche Add-on-Checks bei welchem Risiko-Signal gelten, z.B. BOLA bei user-data, Cert-Pinning bei mobile+public, Anti-Cheat bei competitive-games). Wird in Phase A nach der Security-Risiko-Frage (Frage 12) gelesen; bei other oder Custom per websearch Custom-Template gebaut. Der security-review-Subagent ist ein fester Workflow-Schritt und wird IMMER gebootet.
• references/review-log.md — Review-Log: datierte Einträge mit Anlass, Methode, Fundings, bestätigten Konfigurationen (mit Originalzitat, Quelle: Autor + Titel + Datum + URL, und 'Warum relevant für diesen Skill'). Enthält einen Quellen-Index aller abgerufenen Websearch-Ergebnisse. Lesen, wenn man nachvollziehen will, warum eine Konfiguration so ist wie sie ist; erweitern bei neuen Reviews.

Voraussetzungen

• OpenCode (mit Skill-System)
• git
• python3 (fuer workspace.yml-Parser und JSON-Validierung)
• optional: PyYAML (pip3 install pyyaml) — ohne PyYAML fallen workspace_check.sh / workspace_status.sh auf das Fallback-Manifest zurueck
• optional: gh CLI (fuer GitHub-Repo-Erstellung, falls gewuenscht)
• Der Skill liegt unter /Users/noahk/.agents/skills/workspace-bootstrap/ (OpenCode-Skills-Ordner)

Verwendung

1. Automatisch (empfohlen): In einer OpenCode-Session eine Trigger-Phrase verwenden, z.B.:

   • "Ich will ein neues Projekt <name> aufsetzen mit Subprojekten <a>, <b>, <c>"
   • "Richte mir einen Workspace analog zu <vorbild> ein"
   • Der Skill feuert automatisch und startet die Interview-Phase.

2. Manuell (falls der Skill nicht triggert): Den Skill explizit laden:

   • "Nutze den workspace-bootstrap Skill um ein neues Projekt aufzusetzen"
   • Oder den Skill-Pfad referenzieren.

3. Ablauf:

   • Beantworte die Interview-Fragen (15 Punkte)
   • Reviewe den Plan, den der Skill in Phase A erstellt
   • Beantworte offene Fragen (Lizenzen, MCPs, etc.)
   • Der Skill fuehrt Phase B aus (Sibling-Repos + Meta-Updates)
   • Der Skill validiert (workspace_check.sh muss PASS)
   • Der Skill prueft Diffs (review-diff)
   • Der Skill aktualisiert Doku
   • Der Skill erstellt Retrospektive + Explanation
   • Fertig: vollstaendiges Workspace steht.

Was der Skill NICHT macht

• Er erstellt keinen Code/Content in Siblings ohne approved Plan.
• Er aktiviert keine MCPs ohne Nutzerfreigabe.
• Er erfindet keine projekt-spezifischen Standards — er fragt den Nutzer.
• Er zerstoert keine bestehenden Repos' .git/ — er erweitert nur.
• Er macht keinen git push (orchestrator-interne Regel) — der Nutzer muss selbst pushen.
• Pattern (b) Monorepo, (c) Plugin-Workspace, (d) Custom sind als Extension Points markiert — v1 implementiert voll Pattern (a) Meta-Repo + Siblings.

Pattern-Typen

Der Skill unterstuetzt 4 Pattern:

• (a) Meta-Repo + Siblings (wecouple/video-blog style) — voll implementiert in v1
• (b) Monorepo with workspace docs — Extension Point
• (c) Plugin-Workspace — Extension Point
• (d) Custom — Extension Point

Vorbildprojekte

Der Skill basiert auf drei Projekten:

• /Users/noahk/Documents/work/wecouple_projekt/wecouple/ — Multi-Repo-Orchestrierung mit Meta-Repo, Sibling-Repos mit eigenem Git, workspace.yml, workspace_check.sh, AGENTS.md-Sibling-Template.
• /Users/noahk/Documents/work/nak-hopper-game/docs/ — Vollstaendige docs/ai/-Baeume pro Subprojekt, Learning Feedback Loop (specs/plans/explanations/retrospectives).
• /Users/noahk/Documents/work/video-blog/ — Neuestes Vorbild, kombiniert beide Patterns, mit Git-LFS, license-tracking, ElevenLabs-MCP, DaVinci-MCP-TODO.

Entwicklung und Tests

• v1 entworfen aus dem video-blog-Setup.
• Review durch review-diff-Agent: GO MIT HINWEISEN, 6 Findings behoben (2 kritisch: fehlende permission:-Frontmatter + @elevenlabs-Tippfehler; 4 mittel: Skeleton-Default-Texte, workspace.yml-Header, vorbild-Fallback, Tippfehler).
• 2 Testfaelle validiert:
  • Testfall 1 (podcast-blog): 4 Repos (meta + episodes + assets + shared-templates), Git-LFS in assets/, license-tracking.md, CC0-Lizenz, ElevenLabs-MCP → workspace_check.sh PASS.
  • Testfall 2 (data-science-blog): 4 Repos (meta + notebooks + articles + shared-templates), kein Git-LFS, kein MCP, MIT-Lizenzen, Python-spezifische QA-Checkliste → workspace_check.sh PASS.
• Iteration 2: 3 Verbesserungen aus Test-Feedback eingearbeitet (CC0-curl-Hinweis, konkretes WORKSTREAM_PURPOSE_TABLE-Template, PyYAML-Optional-Hinweis).

Lizenz

MIT — dieser Skill ist frei verwendbar.

GitHub

Privates Repository: https://github.com/DerKellerBlock/workspace-bootstrap

Siehe auch

Verwandte Skills:

• writing-plans — fuer das Schreiben von Implementierungs-Plaenen.
• subagent-driven-development — fuer das Ausfuehren von Plaenen mit unabhaengigen Tasks.
• brainstorming — fuer die Anforderungs-Erkundung vor der Implementierung.