Code Intelligence Actions

CRUD-Operationen für Code mit automatischen Subtasks

Übersicht

Code Intelligence Actions erweitern das Task-System um strukturierte Code-Operationen. Jede Aktion folgt dem CRUD-Prinzip und generiert automatisch die passenden Subtasks mit Qualitätsprüfungen.

1. Grammatik
2. Verben (statisch)
3. Scope (Zuordnung)
4. Domain (dynamisch)
5. Komponente
6. Projekt
7. Sprache
8. Optionen
9. Subtasks
10. Gates
11. Contracts
12. Templates
13. Prozess (Beispiel)
14. Simulation (Refactoring)
15. Architektur (Modulares System)

Grammatik

Syntax

<verb> <domain>:<komponente> in <projekt> <sprache> [optionen] "<beschreibung>"

Bestandteile

Beispiele

create code:controller in masterdev php "UserController"
read code:service in masterdev php "PaymentService verstehen"
update doku:page in masterdev markdown "/codeintelligence/hooks"
delete content:page in karlkratz html "alte Landingpage"
create config:file in freund json "neue Hook-Config"
update data:table in masterdev sql "users um role erweitern"

CRUD-Operationen (Verben)

Vier grundlegende Aktionen für alle Code-Operationen. Jede Aktion generiert automatisch die passenden Subtasks mit Projekt- und Sprach-spezifischen Prüfungen.

Die vier Verben

Beispiele

create code:service in masterdev php "UserService"
read code:controller in masterdev php "AuthController verstehen"
update code:service in masterdev php "UserService um Rollen erweitern"
delete code:helper in masterdev php "LegacyHelper entfernen"

Scope

Zuordnung dynamischer Elemente zu Kontext.

Prinzip

Jedes dynamische Element hat Scope-Attribute. * = gilt für alle.

Scope-Attribute

Auflösung

create code:service in masterdev php "UserService"
                ↓
Filter 1: project   = * OR contains "masterdev"
Filter 2: domain    = * OR contains "code"
Filter 3: component = * OR contains "service"
Filter 4: language  = * OR contains "php"
                ↓
Alle passenden Elemente werden angewendet.

Scope pro Element-Typ

Domain

Bereich, in dem die Aktion ausgeführt wird.

Typ

Dynamisch. Wird aus Projekt-Konfiguration geladen.

Quelle

config/{projekt}/domains.json

Bekannte Domains

Komponente

Typ des Objekts innerhalb einer Domain.

Typ

Dynamisch. Abhängig von Domain und Projekt.

Quelle

code_intelligence.code_entities → type
config/{projekt}/komponenten.json

Bekannte Komponenten

Projekt

Codebase, in der die Aktion ausgeführt wird.

Typ

Dynamisch. Registrierte Projekte im System.

Quelle

code_intelligence.code_projects → project_key

Bekannte Projekte

Sprache

Programmiersprache für code-Domain Aktionen.

Typ

Dynamisch. Abhängig von Projekt und Domain.

Quelle

code_intelligence.code_files → file_path extension
config/{projekt}/sprachen.json

Bekannte Sprachen

Optionen

Optionale Flags zur Steuerung der Ausführung.

Typ

Statisch. Gelten für alle Aktionen.

Bekannte Optionen

Beispiele

create code:service in freund python --dry-run "CacheService"
delete code:helper in masterdev php --force "LegacyHelper"
update data:table in masterdev sql --verbose "users erweitern"

Subtasks

Automatisch generierte Teilaufgaben basierend auf Verb, Domain und Template.

Typ

Dynamisch. Generiert aus Template bei Task-Erstellung.

Quelle

templates/{verb}/{domain}/{komponente}.json → subtasks[]
masterdev.tasks → parent_task_id

Status

Standard-Subtasks pro Verb

Subtask-Phasen

Gates

Qualitätsprüfungen, die vor Abschluss eines Subtasks bestanden werden müssen.

Typ

Dynamisch. Abhängig von Projekt, Domain und Sprache.

Quelle

config/{projekt}/gates.json
config/gates/{sprache}.json

Bekannte Gates

Contracts

Regeln und Einschränkungen, die während der Ausführung gelten.

Typ

Dynamisch. Abhängig von Projekt und Domain.

Quelle

masterdev.contracts → project_key, domain
freund code contracts {file}

Severity

Contract-Typen

Bekannte Contracts

Templates

Vorlagen für die Generierung von Subtasks und Code-Strukturen.

Typ

Dynamisch. Abhängig von Verb, Domain, Komponente und Sprache.

Quelle

config/templates/{verb}/{domain}/{komponente}.json
config/templates/{sprache}/{komponente}.json

Hierarchie

Placeholders

Bekannte Templates

Prozess

Beispiel: Python-Service im Projekt freund erstellen.

Eingabe

create code:service in freund python "CacheService"

1. Parsing

2. Scope-Auflösung

Filter: project=freund, domain=code, component=service, language=python

Sprache

Template

Gates

Contracts

3. Subtask-Generierung

Verb create → Template-Subtasks:

4. Task erstellt

Task #3400: create code:service in freund python "CacheService"
├── Subtask #3401: analyse
├── Subtask #3402: implementierung
│   └── Gates: syntax_check, import_test
├── Subtask #3403: validierung
│   └── Gates: type_check, unit_test, contract_check
└── Subtask #3404: abschluss
    └── Gates: impact_check

Aktive Contracts:
- no_hardcoded_paths (critical)
- parameter_binding (critical)
- no_curl_wget (major)
- no_direct_mysql (major)
- class_documentation (minor)

Template: config/templates/python/service.json
Ziel: /var/www/tools/freund/src/services/cache_service.py

Simulation

Vollständiger Prozess: PaymentService in masterdev refactoren.

Eingabe

update code:service in masterdev php "PaymentService auf neue API umstellen"

Phase 0: Parsing

Phase 1: Scope-Auflösung

Filter: project=masterdev, domain=code, component=service, language=php

1.1 Template laden

→ Geladen: config/templates/php/service.json

1.2 Gates filtern

→ Aktive Gates: syntax_check, cqs_clean, type_check, unit_test, contract_check, impact_check

1.3 Contracts filtern

→ Aktive Contracts: 7 (davon 2 critical, 3 major, 2 minor)

Phase 2: Task-Erstellung

INSERT INTO masterdev.tasks (title, type, status, project, domain, component, language)
VALUES ('update code:service in masterdev php "PaymentService..."', 'code_action', 'pending', 'masterdev', 'code', 'service', 'php')
→ Task #3500 erstellt

2.1 Subtasks generieren

Template für update definiert 5 Subtasks:

INSERT INTO masterdev.tasks (parent_task_id, title, order_num, gates, status)
VALUES
  (3500, 'analyse', 1, NULL, 'pending'),           → #3501
  (3500, 'baseline', 2, NULL, 'pending'),          → #3502
  (3500, 'implementierung', 3, '["syntax_check","cqs_clean"]', 'pending'),  → #3503
  (3500, 'validierung', 4, '["type_check","unit_test","contract_check"]', 'pending'),  → #3504
  (3500, 'abschluss', 5, '["impact_check"]', 'pending')  → #3505

Phase 3: Ausführung

Subtask #3501: analyse

Output:
- Datei: /var/www/dev.karlkratz.de/src/Services/PaymentService.php
- Zeilen: 245
- Abhängigkeiten: 12 (OrderController, CheckoutService, ...)
- Aktive Contracts: 7
- Geschätzter Impact: MEDIUM (12 abhängige Dateien)

→ Status: completed

Subtask #3502: baseline

INSERT INTO karlkratz_de.file_backup_history (file_path, reason, user_type)
VALUES ('/var/www/.../PaymentService.php', 'Baseline vor Refactoring: PaymentService auf neue API', 'claude-code')
→ backup_id: 4711

→ Status: completed

Subtask #3503: implementierung

→ Edit: PaymentService.php (87 Zeilen geändert)

Gate: syntax_check
$ php -l src/Services/PaymentService.php
No syntax errors detected
→ PASSED

Gate: cqs_clean
$ cqs masterdev
PaymentService.php: 0 issues
→ PASSED

→ Status: completed

Subtask #3504: validierung

Gate: type_check
$ phpstan analyse src/Services/PaymentService.php --level=6
[OK] No errors
→ PASSED

Gate: unit_test
$ phpunit tests/Services/PaymentServiceTest.php
OK (12 tests, 34 assertions)
→ PASSED

Gate: contract_check
$ freund code contracts src/Services/PaymentService.php
Checking 7 contracts...
✓ no_hardcoded_paths
✓ no_inline_css
✓ parameter_binding
✓ backup_before_edit (backup_id: 4711)
✓ no_curl_wget
✓ no_direct_mysql
✓ class_documentation
→ PASSED (0 violations)

→ Status: completed

Subtask #3505: abschluss

Gate: impact_check
$ freund code impact PaymentService --after
Analysing changes...
- Changed: 87 lines
- Affected files: 12
- Breaking changes: 0
- API compatibility: maintained
→ PASSED

$ ./change.sh src/Services/PaymentService.php "Refactoring: PaymentService auf neue API umgestellt"
→ Entity updated in code_intelligence
→ Embeddings regenerated
→ Graph updated

→ Status: completed

Phase 4: Task-Abschluss

UPDATE masterdev.tasks SET status = 'completed', completed_at = NOW()
WHERE id = 3500

Task #3500: update code:service in masterdev php "PaymentService auf neue API umstellen"
├── #3501 analyse       [completed]
├── #3502 baseline      [completed] backup_id=4711
├── #3503 implementierung [completed] gates: 2/2 passed
├── #3504 validierung   [completed] gates: 3/3 passed
└── #3505 abschluss     [completed] gates: 1/1 passed

Dauer: 12 min
Gates: 6/6 passed
Contracts: 7/7 satisfied
Backup: #4711 (restore verfügbar)

Architektur

Modulares Prozess-System mit Vererbung und Conditions.

Dateistruktur

config/prozesse/
├── _schema/           # JSON Schemas
├── _base/             # Verben, Domains, Gates, Contracts
├── _components/       # Sprach-spezifisch (php, python, sql)
├── _projects/         # Projekt-Overrides
└── prozesse/          # Konkrete Prozess-Definitionen

Vererbung

Merge-Logik

extends[0] + extends[1] + extends[2]
    + _projects/{projekt}.json
    + prozess-overrides
    = Finale Definition

Arrays:  _add = anhängen, _remove = entfernen
Objects: Deep merge (später überschreibt)

Conditions

{
  "contracts": ["no_hardcoded_paths"],
  "contracts_if": [
    {"when": {"project": ["masterdev"]}, "add": ["backup_before_edit"]},
    {"when": {"component": "repository"}, "add": ["no_direct_sql"]},
    {"when": {"verb": "delete"}, "add": ["require_impact_approval"]}
  ]
}

Variablen

Beispiel: Minimale Prozess-Definition

{
  "id": "create-code-service-php",
  "extends": ["verbs/create", "domains/code", "components/php"],

  "component": "service",
  "projects": "*",

  "contracts_if": [
    {"when": {"project": ["masterdev"]}, "add": ["backup_before_edit"]}
  ],

  "template": {
    "skeleton": "templates/php/service.tpl",
    "path": "src/Services/{name}Service.php"
  }
}

Validierung

prozess validate create-code-service-php

# Prüft:
# ✓ Schema-Konformität
# ✓ extends-Referenzen existieren
# ✓ Gates/Contracts existieren
# ✓ Variablen vollständig