"Spec-Driven Necromancy: Building a Gothic Customs & Courier Oracle with Kiro for Kiroween 2026" published: true

Ariel Cuenca — Fri, 13 Nov 2026 03:32:40 +0000

This article was written as part of the **Kiroween 2026 hackathon.

International online shopping in Ecuador comes with a terrifying boss fight: Customs Regulations (SENAE). Between the Category B (4x4 Rule) thresholds, weight conversions, annual quotas, and hybrid tracking numbers that switch carriers mid-flight, a single miscalculation can turn a cheap haul into a nightmare of unexpected taxes.

For the Kiroween 2026 hackathon (Costume Contest category), I built PhantasmTrack · GrimCourier—a gothic customs grimoire and multi-courier tracking oracle disguised as an interactive haunted web experience, engineered from the ground up using Kiro IDE.

Live Deployment: https://phantasm-track-hazel.vercel.app
GitHub Repository (MIT): https://github.com/ArielSebas/phantasm-track

1. The Real-World Problem: Ecuador's SENAE 4x4 Customs Labyrinth

When importing packages into Ecuador via platforms like Temu or US freight forwarders (LaarBox, Upper), buyers must navigate strict customs rules:

Category B (4x4 Exemption): Packages weighing ≤ 4 kg (8.81 lb) AND with an FOB value ≤ $400 USD pay a flat $20.00 USD SENAE fee (0% Ad-Valorem, 0% FODINFA, 0% IVA).
General Regime Penalty: Exceeding either 4 kg or $400 USD triggers FODINFA (0.5%), Ad-Valorem tariff (20%), and IVA (15%).
Annual Mana Cap: Every citizen has a $1,600 USD annual limit under the 4x4 regime.
Hybrid Tracking Numbers: A tracking code starting with TMLC... routes through LaarCourier, whereas SP...EC is a dual-stage hybrid tracking number handled first by Far International and then handed over locally to Urbano Express or Servientrega.

2. How Kiro Transformed the Development Workflow

Instead of jumping straight into UI components and hoping the math worked, I used Kiro's structured .kiro/ architecture to separate formal domain rules from the haunting interface.

A. EARS Specifications (`.kiro/specs/customs-grimoire/`)

Using Kiro's spec workflow (requirements.md, design.md, and tasks.md), I defined 12 formal requirements using strict EARS (Easy Approach to Requirements Syntax).

For example, before writing the tax engine, Kiro helped formalize exact boundary conditions:

WHEN a shipment's weight is ≤ 4.00 kg and FOB value is ≤ $400.00 USD, THE SYSTEM SHALL apply the Category B flat fee of $20.00 USD.
IF either threshold is exceeded, THE SYSTEM SHALL transition to the General Regime calculation and compute FODINFA, Ad-Valorem, and IVA rounded strictly to 2 decimal places (round2).

B. Property-Based Testing + Kiro Hooks (`.kiro/hooks/domain-pbt-check.json`)

Floating-point arithmetic (0.1 + 0.2 !== 0.3) is fatal in financial and customs calculators, especially when converting between pounds and kilograms (1 kg = 2.20462 lb).

In design.md, we mapped requirements to Correctness Properties tested with Vitest and fast-check. Then, I configured a Kiro Hook (domain-pbt-check.json) that automatically runs npx vitest run whenever any file in src/domain/customs/ is modified. Every edge case—from 3.999 kg to 4.001 kg and annual quota transitions (SAFE, WARNING, CRITICAL)—was mathematically verified across hundreds of generated test cases.

C. Steering Files (`.kiro/steering/`)

By configuring product.md, structure.md, and tech.md, Kiro always understood the project's constraints:

Tech Stack: Next.js 16.4.4 (App Router), React 19, TypeScript, Tailwind CSS v4.
Architectural Boundary: Never mix UI animations with src/domain/customs/.

3. Crafting the "Costume Contest" Haunting UI

With the domain layer locked down by Kiro Specs and PBT, I focused on making the interface unforgettable:

Interactive SVG Guardians (SideDecorations.tsx): The Messenger Skull (left) and Lord Pumpkin (right) react to user actions with 5 full-screen cinematics (welcome, inscribe at the packing table, advance with a SENAE customs scanner, deliver with a hand-to-hand package delivery, and banish with a broom sweep).
The Multi-Courier Tracking Oracle (TrackingOracle.tsx): Automatically detects TMLC... (LaarCourier) and SP...EC (Temu Ecuador Dual-Stage tracking showing both Stage 1 International and Stage 2 Local Delivery), complete with 1-click demo buttons and instant ledger inscription.
The Messenger Raven (/api/suggestions): A hardened feedback channel using parallel dispatch (Web3Forms + Discord Webhook) protected by IP rate-limiting (HTTP 429), Honeypot anti-bot traps, and Discord mention sanitization (@everyone / @here).

4. Key Takeaways from Building with Kiro

Kiro bridged the gap between creative UI polish and rigorous software engineering. Having .kiro/specs keep track of tasks (14/14 completed) while .kiro/hooks guarded the customs math allowed me to iterate rapidly on responsive SVG animations, bilingual support (ES | EN), and security headers without breaking a single domain rule.

Try PhantasmTrack · GrimCourier live at https://phantasm-track-hazel.vercel.app and check out the .kiro/ directory in the GitHub repo!

DEV Community: Ariel Cuenca