DES-374: Token candidates + parallel pipeline + sub-agent fix proposals

[OJBoon]

Jira: DES-374 — Lotus Design System (Epic)
Stacked on: #4 (typography parity)

Summary

Three additions, all building on the same audit run.

1. Token candidates from iOS

New scripts/token-candidates.mjs finds hardcoded values used 3+ times in iOS code that aren't already Lotus tokens. Classifies each as:

• 🔁 use-existing-token — value matches an existing token, just typed as a literal. Adoption gap.
• 🎯 near-miss — value within 1pt of an existing token. Likely typo / off-by-one.
• ➕ new-candidate — value isn't close to anything. Worth proposing as a new Figma token.

Real findings on the live iOS repo include 10pt spacing used 5× — iOS already has LotusSpacing.spacingSemiSmall = 10 but Figma doesn't. The script surfaces this as a "new-candidate" for Figma. Other findings: 20× literal 12pt (should use spacingSmall), 5pt near-miss of spacingXXSmall=4, etc.

Excludes the colour-system definition files (UIColor+JP.swift, UIColor+Design2.0.swift, UIColor+fromHEX.swift) so their internal hex literals don't surface as candidates.

2. Parallel pipeline

Stage 1 (four extract scripts: figma-fetch, parse-colours, parse-typography, scan-ios) and Stage 2 (three analysers: colour-parity, typography-parity, token-candidates) have no inter-script dependencies. Now invoked via simultaneous Bash tool calls in a single message. Roughly halves wall-clock time vs the old sequential run.

SKILL.md now leads with a four-stage mermaid diagram (Stage 1 / 2 / 3 / 4) and explicitly tells the orchestrator: "send these as four parallel Bash tool calls in one message".

3. Per-file fix-proposal sub-agents (new Stage 3)

New stage spawns one general-purpose Task agent per worst-offender file (top 10, gated to ≥5 violations). Each sub-agent reads its file with the full Lotus token namespace as context, then proposes concrete migrations as JSON: line, current snippet, proposed snippet, token used, confidence, optional caveat.

Orchestrator aggregates results to /tmp/fix-proposals.json. build-report.mjs renders a new "Suggested fixes — worst-offender files" section with one table per file.

Smoke-test on 4 real files produced 47 high-confidence migrations including:

• .jpGreen → LotusColours.Brand.justparkGreen
• Font.heavy.font(forSize: 16) → LotusTypography.bodyMediumBold
• .padding(8) → .padding(LotusSpacing.spacingXSmall)
• .cornerRadius(4) → .cornerRadius(LotusCorners.radiusXSmall)
• Plus medium-confidence ones with caveats — e.g. legacy jpDarkGray6 → LotusColours.Text.secondary ("muted body/secondary text colour throughout this cell").

allowed-tools adds Task. Skill degrades gracefully if Task isn't available — Stage 3 just gets skipped.

Architectural notes

The skill now uses three different Claude Code primitives in concert:

• Bash for the data pipeline (deterministic scripts)
• Task / sub-agents for narrative reasoning (per-file migration proposals — something a script can't do)
• Write for aggregation (orchestrator stitches sub-agent JSON together)

This is the right division of labour. Scripts handle volume; sub-agents handle judgement. The report builder consumes both.

Test plan

• Full pipeline runs end-to-end against ~/code/ios with focused Lotus tab.
• Stage 1 + 2 confirmed parallel via background Bash calls (4 then 3, all completing within seconds of each other).
• Stage 3 spawned 4 sub-agents in parallel; each returned valid JSON; aggregated successfully.
• build-report.mjs renders new sections; degrades gracefully when their inputs are absent.

Followups (not in this PR)

• Drift comparison between consecutive audits — the only one of the four "advanced features" we discussed not shipped here.
• Consider auto-excluding Lotus/-prefixed files from worstFiles[*] so a definition file like UIColor+Design2.0.swift never tops the list.

🤖 Generated with Claude Code

[gitstream-cm]

🚨 gitStream Monthly Automation Limit Reached 🚨

Your organization has exceeded the number of pull requests allowed for automation with gitStream.
Monthly PRs automated: 250/250

To continue automating your PR workflows and unlock additional features, please contact LinearB.