full-stack-feature

What this skill does

# Full-Stack Feature Development Skill

## Regeln

1. **AUTO-ADVANCE:** Nach Phasen 2–6 sofort nächste Phase starten — NICHT stoppen. _(Erzwungen durch Stop Hook: decision:block)_
2. **APPROVAL GATES:** Nach Phasen 0, 1, 7, 8, 9 → `status = "awaiting_approval"`, User fragen, STOPP. _(UserPromptSubmit Hook injiziert Rollback-Regeln bei User-Antwort)_
3. **Kein Code schreiben:** Hook blockiert Edit/Write. Jede Änderung → `Task(byt8:AGENT)`.
4. **Nicht explorieren:** Hook blockiert Task(Explore) und Task(general-purpose). Nur `workflow-state.json` lesen. Agents explorieren und lesen Specs selbst. Bei Rollback-Entscheidungen: **User fragen** statt selbst untersuchen.

### Hook-Enforcement (v7.0)

Vier Hooks steuern den Workflow deterministisch:
- **Stop Hook** (`wf_engine.sh`): JSON `decision:block` erzwingt Auto-Advance. Claude KANN NICHT stoppen bei Phasen 2-6.
- **UserPromptSubmit Hook** (`wf_user_prompt.sh`): Injiziert Workflow-Status und Rollback-Regeln in Claudes Kontext bei jedem User-Prompt.
- **PreToolUse Hook** (`block_orchestrator_code_edit.sh`): Blockiert Code-Edits durch den Orchestrator.
- **PreToolUse Hook** (`block_orchestrator_explore.sh`): Blockiert Task(Explore/general-purpose). Orchestrator MUSS an byt8:Agents delegieren.

---

## Phasen

| Phase | Agent | Typ |
|-------|-------|-----|
| 0 | `byt8:architect-planner` | APPROVAL |
| 1 | `byt8:ui-designer` | APPROVAL |
| 2 | `byt8:api-architect` | AUTO |
| 3 | `byt8:postgresql-architect` | AUTO |
| 4 | `byt8:spring-boot-developer` | AUTO |
| 5 | `byt8:angular-frontend-developer` | AUTO |
| 6 | `byt8:test-engineer` | AUTO |
| 7 | `byt8:security-auditor` | APPROVAL |
| 8 | `byt8:code-reviewer` | APPROVAL |
| 9 | Orchestrator direkt (Push & PR) | APPROVAL |

WIP-Commits werden automatisch vom SubagentStop Hook erstellt (Phasen 1, 3, 4, 5, 6 + Safety Net: Agent-basiert bei Hotfixes).

---

## Startup

### Schritt 1: Cleanup prüfen (PFLICHT!)

**ERSTER Befehl bei jedem Skill-Start:**

```bash
${CLAUDE_PLUGIN_ROOT}/scripts/wf_cleanup.sh
```

| Exit Code | Bedeutung | Aktion |
|-----------|-----------|--------|
| 0 | OK (kein Workflow oder completed → aufgeräumt) | Weiter mit Schritt 2 |
| 1 | BLOCKED (aktiver Workflow gefunden) | STOPP! User entscheidet: fortsetzen oder abbrechen |

**Warum explizit?** Der SubagentStart Hook greift erst bei Task()-Aufrufen. Da der Startup mit Bash-Befehlen beginnt, muss Cleanup explizit passieren.

**Safety Net:** SubagentStart Hook räumt weiterhin bei `status=completed` auf — als Backup falls dieser Schritt übersprungen wird.

### Schritt 2: Prüfe ob Workflow existiert

```bash
cat .workflow/workflow-state.json 2>/dev/null || echo "NEW"
```

- **Wenn existiert:** Lies `status` und `currentPhase`, handle entsprechend.
- **Wenn neu (oder gerade aufgeräumt):** Initialisiere (siehe unten).

### Initialisierung

```bash
cat CLAUDE.md 2>/dev/null | head -10 || echo "No CLAUDE.md"
# Workflow-Struktur erstellen
mkdir -p .workflow/logs .workflow/specs .workflow/recovery
grep -q "^\.workflow/" .gitignore 2>/dev/null || echo ".workflow/" >> .gitignore
git fetch --prune
git branch -r | grep -v HEAD | sed 's/origin\///' | head -10
```

**Frage User:**
1. "Von welchem Branch starten?" (Default: main/develop)
2. "Welches Coverage-Ziel?" (50% / 70% / 85% / 95%)

### State erstellen

```bash
STARTED_AT=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
cat > .workflow/workflow-state.json << EOF
{
  "workflow": "full-stack-feature",
  "status": "active",
  "issue": { "number": ISSUE_NUM, "title": "ISSUE_TITLE", "url": "..." },
  "branch": "feature/issue-ISSUE_NUM-...",
  "fromBranch": "FROM_BRANCH",
  "targetCoverage": COVERAGE,
  "currentPhase": 0,
  "startedAt": "$STARTED_AT",
  "phases": {},
  "context": {}
}
EOF
```

```bash
git checkout -b feature/issue-ISSUE_NUM-kurzer-name
```

Dann Phase 0 starten: `Task(byt8:architect-planner, "Create Technical Specification for Issue #N: Title")`

### Nach Phase 0: APPROVAL GATE (PFLICHT!)

**STOPP! Ändere currentPhase NICHT selbst!**

1. Lies die erstellte Spec-Datei aus `context.technicalSpec.specFile`
2. Zeige dem User eine Zusammenfassung der Spec
3. Frage: "Spec OK? Soll ich fortfahren?"
4. **WARTE auf User-Antwort** — der Stop-Hook setzt `status = "awaiting_approval"`
5. ERST nach User-Approval: Phasen skippen und nächste Phase starten

**NIEMALS:** `currentPhase` ändern bevor User approved hat!

---

## Agent-Aufruf (File Reference Protocol)

Vor jedem Aufruf: `Read(.workflow/workflow-state.json)` → nur Pfade extrahieren, keine Spec-Dateien lesen.

### Phase-Dependency-Map

| Phase | SPEC FILES im Prompt |
|-------|---------------------|
| 1 | `technicalSpec.specFile` |
| 2 | `technicalSpec.specFile` |
| 3 | `technicalSpec.specFile`, `apiDesign.apiDesignFile` |
| 4 | `technicalSpec.specFile`, `apiDesign.apiDesignFile`, `migrations.databaseFile` |
| 5 | `technicalSpec.specFile`, `apiDesign.apiDesignFile` + `wireframes.paths` |
| 6 | `technicalSpec.specFile` |
| 7 | `technicalSpec.specFile` |
| 8 | `technicalSpec.specFile`, `apiDesign.apiDesignFile` |

### Task()-Prompt Format

```
Task(byt8:[agent], "
Phase [N]: [Name] for Issue #[NUM]

## SPEC FILES (LIES DIESE ZUERST mit dem Read-Tool!)
- Technical Spec: [context.technicalSpec.specFile]
- [Weitere gemäß Dependency-Map]

## WORKFLOW CONTEXT
- Issue: #[NUM] - [TITLE]
- Target Coverage: [targetCoverage]%

## YOUR TASK
[Anweisungen]
")
```

---

## Phase Skipping

Wenn eine Phase übersprungen wird (z.B. Backend-only Feature, keine DB-Änderungen):

1. `phases[N].status = "skipped"` + `reason` setzen
2. **Minimal-Context PFLICHT:** `context.CONTEXT_KEY = { "skipped": true, "reason": "..." }`

Der Guard-Hook prüft sowohl `phases[N].status` als auch `context.*` Keys. Defense-in-Depth: beides setzen.

Beispiel für Backend-only Feature (Phasen 1-3 überspringen):
```bash
jq '
  .phases["1"] = {"name":"ui-designer","status":"skipped","reason":"Backend-only"}
  | .context.wireframes = {"skipped":true,"reason":"Backend-only"}
  | .phases["2"] = {"name":"api-architect","status":"skipped","reason":"No API changes"}
  | .context.apiDesign = {"skipped":true,"reason":"No API changes"}
  | .phases["3"] = {"name":"postgresql-architect","status":"skipped","reason":"No DB changes"}
  | .context.migrations = {"skipped":true,"reason":"No DB changes"}
' .workflow/workflow-state.json > tmp && mv tmp .workflow/workflow-state.json
```

---

## Phase 7: Security Audit

User entscheidet nach Findings:
- **Weiter:** `currentPhase = 8`, `status = "awaiting_approval"`
- **Fixen:** Rückdelegation (siehe unten), max 3 Iterationen. Context löschen: `securityAudit`, `testResults`.

## Phase 8: Code Review

- **APPROVED:** `currentPhase = 9` + `status = "awaiting_approval"`, User fragen: "PR erstellen?"
- **CHANGES_REQUESTED:** Rückdelegation (siehe unten), max 3 Iterationen.

## Phase 9: Push & PR

_(Status ist bereits `awaiting_approval` aus Phase 8 Approval)_

1. User fragen: "PR erstellen? Ziel-Branch?" (Default: `fromBranch`)
2. PR-Body generieren aus `context.*` Keys
3. Bei Ja:
   ```bash
   # Status auf active + pushApproved setzen (Guard-Hook prüft!)
   jq '.status = "active" | .pushApproved = true' .workflow/workflow-state.json > tmp && mv tmp .workflow/workflow-state.json
   git push -u origin $BRANCH
   gh pr create --base $INTO_BRANCH --title "feat(#N): Title" --body "$PR_BODY"
   ```
4. State: `status = "completed"`
5. Zusammenfassung mit Dauer anzeigen (`startedAt` bis jetzt)

---

## Rückdelegation

### Fall 1: Revision der aktuellen Phase

User will Änderung an aktueller Phase → `Task(AKTUELLER_AGENT, "Revise: FEEDBACK")` → erneut Approval Gate.

### Fall 2: Rollback auf frühere Phase

Typische Situationen: User will bei Phase 7/8 noch UI-Änderungen, Backend-Fixes, oder Feature-Erweiterungen.

| Fix-Typ | Ziel | Agent |
|---------|------|-------|
| Spec / Architektur | Phase 0 | `byt8:architect-planner` |
| Wireframes / UI | Phase 1 | `byt8:ui-designer` |
| API Design | Phase 2 | `byt8:api-architect` |
| DB Migra