workflow-clean-code-angular

<objective> Guarantee that Angular code in the target scope meets the standard of a senior developer who crafted it by hand — clean, clear, no AI slop, proper architecture, correct signal patterns, and clear ViewModel separation. </objective>

<philosophy> This isn't a linter. Linters catch syntax. This skill catches design decisions — the kind of issues only a senior engineer spots during code review.

Three things that separate senior-crafted code from AI-generated code:

1. Nothing unnecessary — no defensive checks for impossible scenarios, no abstractions with one consumer, no comments that restate the code
2. Right responsibility in the right place — stores own data transformations, components coordinate UI, templates just bind
3. Consistent patterns — every store follows the same anatomy, every component follows the same structure, no surprise conventions

</philosophy>

<quick_start>

/clean-code-angular feature/budget/          # Standard audit
/clean-code-angular -a --deep feature/       # Deep audit, auto mode
/clean-code-angular --quick core/            # Quick surface scan
/clean-code-angular --slop --vm feature/     # Focus: AI slop + ViewModel
/clean-code-angular diff main                # Audit changes vs main
/clean-code-angular pending                  # Audit uncommitted changes

</quick_start>

<parameters>

Default depth (no flag): grep + targeted semantic analysis of key files. --deep enables all specialist domains.

</parameters>

<workflow>

SCAN ─────────────────► APPLY ─────────────► VERIFY
  │                       │                     │
  ├─ Parse scope          ├─ Load docs/refs     ├─ Lint + type-check
  ├─ Launch specialists   ├─ Apply fixes        ├─ Run tests
  │  (up to 10 agents)    │  (parallel agents)  ├─ Team lead final
  ├─ Team lead review     ├─ Team lead          │  craftsman review
  ├─ Adversarial review   │  coherence check    ├─ Adversarial final
  │  (if --adv)           └─ Track progress     │  challenge (if --adv)
  └─ Consolidated issues                        └─ Commit

</workflow>

<agent_model>

Agent Architecture

The skill scales agent count based on flags:

Standard/Deep Mode — Flat Architecture

Up to 10 domain-focused specialists launched in parallel. Count scales with scope size:

The 10 Domains

Testing quality is checked when --testing or --deep or --ultra is enabled. The testing specialist reads .spec.ts files in scope and evaluates against references/testing-patterns.md.

Ultra Mode — Multi-Tier Cluster Architecture

15 specialists organized in 5 clusters, each with a dedicated cluster lead. Each specialist loads exactly the reference files it needs — no bloat.

Cluster 1: Architecture → Architecture Lead

Cluster 2: Signals & State → Reactivity Lead

Cluster 3: Code Quality → Quality Lead

Cluster 4: UI & Templates → Frontend Lead

Cluster 5: Testing & Security → Security Lead

Flow:

15 specialists (parallel) → 5 cluster leads (parallel) → Grand Tech Lead → Adversarial

Team Lead (Standard/Deep)

Launched after specialists complete. A senior Angular architect who:

• Merges all specialist reports into one deduplicated list
• Removes false positives by reading the actual code
• Resolves contradictions between specialists
• Adds cross-cutting observations no single specialist caught
• Prioritizes the final issue list
• Verifies fix coherence in step-02
• Does final craftsman review in step-03

Cluster Leads (Ultra)

Each cluster lead receives ONLY its 3 specialists' reports. They:

• Deduplicate within their domain
• Resolve contradictions between their specialists
• Add domain-specific cross-cutting observations
• Output a focused domain report (max 10 issues per cluster)

Grand Tech Lead (Ultra)

Receives all 5 cluster lead reports. A principal Angular architect who:

• Merges all cluster reports into one unified list
• Resolves cross-cluster contradictions (e.g., Architecture says "move to core" but Quality says "inline it")
• Identifies systemic patterns across clusters (e.g., "every file has the same DI problem")
• Prioritizes by business impact, not just technical severity
• Caps at 30 issues, notes total if more
• Adds a "systemic diagnosis" section: what's the ROOT CAUSE behind the pattern of issues?

Adversarial Reviewer (--adv or --ultra)

Launched after the team/grand lead. A skeptical senior engineer who:

• Challenges each finding: "Is this really wrong? Could there be a valid architectural reason?"
• Hunts false positives: reads the actual code for each flagged issue and checks if context was missed
• Hunts missed issues: reads ALL files in scope looking for issues that ALL specialists + leads missed
• Questions severity: "Is this really Critical or just Important? Would a production user notice?"
• Checks RxJS false flags: verifies that valid RxJS patterns aren't flagged as signal anti-patterns
• Checks Angular version assumptions: verifies recommendations match Angular 21+
• Checks against project profile: verifies that no finding contradicts the project's documented conventions from {project_profile}

Output: a correction table listing upgrades, downgrades, removals, and additions to the lead's findings.

</agent_model>

<state_variables>

</state_variables>

<reference_files>

</reference_files>

<entry_point>

Load steps/step-01-scan.md

</entry_point>

<step_files>

</step_files>

<execution_rules>

• Discover project context BEFORE scanning — read CLAUDE.md, package.json, angular.json, eslint config to build {project_profile}
• Filter ALL findings through {project_profile} — never flag patterns that match documented project conventions
• Load one step at a time
• Scale agent count to scope size (economy mode = 0 agents, direct tools only)
• Use the Grep tool for pattern detection (not bash grep)
• Scope-aware: only touch files within the specified scope
• Every finding: file:line reference required
• Every fix: source citation required
• Team lead reviews after scan AND after apply

</execution_rules>

<success_criteria> After this workflow, the scoped code reads as if a senior Angular developer wrote it by hand:

• Zero architecture violations
• Modern signal patterns throughout
• Stores follow 6-section anatomy with proper ViewModel selectors
• No AI slop — no unnecessary comments, abstractions, or defensive code
• Clean ViewModel separation — stores transform, components bind, templates stay simple
• Consistent patterns across all files in scope
• Quality check passes (lint + type-check + format)
• Tests pass
• If --adv: adversarial review found no missed issues or false positives

</success_criteria>