TL;DR

With Kiro as our AI-powered IDE and a tight spec, we shipped a working Visibility Coach for restaurants in hours, not weeks. Kiro handled spec-to-code, enforced steering & hooks, and helped us produce a stable CLI that generates Top-5 Next Best Actions plus a one-page Markdown playbook. We closed the loop with tests, type safety, and format/lint gates to make the demo rock-solid for the hackathon.

---

Problem & Outcome

Local restaurants and cafés are great at hospitality—but struggle with digital visibility. Our goal was to give them confidence and clarity: “Do these five things next,” packaged in a shareable, one-page playbook.

Outcome: a minimal, reproducible pipeline from a restaurant URL/mini-profile → scores → plan → Markdown. Everything is small, deterministic, and built to demo in under three minutes.

---

Why Kiro

We used Kiro to collapse the “talk → code → test → iterate” loop into a single, guided flow:

1. Spec-to-Code: We wrote a crisp spec (/.kiro/specs/visibility_coach.md) with user stories, acceptance criteria, and a test plan.
2. Steering: A /.kiro/steering.yaml defined architecture, coding rules, and quality gates (TypeScript strict, ESLint/Prettier, Jest).
3. Hooks: Lightweight scripts in /.kiro/hooks keep code and tests aligned whenever specs or commits change.

This setup let us stay focused on product outcomes instead of yak-shaving.

---

How We Built It

Architecture (MVP)

• Input: URL or mini profile { name, city, category }

• Core:

  • parser.ts (normalizes input)
  • scorer.ts (deterministic visibility scores)
  • planner.ts (picks exactly 5 actions)

• Renderer: markdown_renderer.ts (one-page plan with LaTeX equation for priority)

Priority formula (transparent & auditable):

$$
\mathrm{priority}(a_i)=w_i\cdot \Delta \mathrm{impact}(a_i) - \mathrm{effort}(a_i)
$$

Kiro-Driven Build Log (highlights)

• Task 1 — Public scaffold with /.kiro (specs, steering, hooks), MIT license, clean README.

• Task 2 — Core + CLI + tests:

  • Type-safe TS modules, unit & snapshot tests.
  • CLI writes output/visibility_playbook.md and prints Top-5 actions.

• Task 2.1 — Hooks stabilized:

  • Prettier formatting + ESLint v9 flat config (ESM), jest transform fixed.
  • Hooks now run cleanly on pre-commit/spec change.

What Kiro actually produced/verified:

• Deterministic outputs for demo.
• Green test runs and formatting/lint gates.
• Repeatable project structure jurors can run quickly.

---

What Worked (Kiro Successes)

• Spec-to-Code you can trust: Kiro turned a single source of truth (the spec) into working code and tests we could iterate on rapidly.
• Fast guardrails: Steering + hooks meant no “it works only once” surprises. Prettier/ESLint/TypeScript/Jest ran in a loop, keeping quality stable.
• Small surface, big clarity: We resisted scope creep (no scraping, no external APIs in MVP), so our 3-minute demo is a clean narrative from spec → run → value.

In numbers (from our runs):

• 8/8 test suites passed
• 12/12 tests passed
• Snapshots: 2/2 passed
• CLI saved the playbook to: output/visibility_playbook.md
• Example console output (excerpt):

Top-5 actions:
1. Tighten visual & copy consistency (priority: 8)
2. Activate UGC with a simple incentive (priority: 8)
3. Post 3 IG reels/week with local hooks (priority: 7)
4. Establish a gentle review cadence (priority: 7)
5. Fix Google Business Profile basics (priority: 5)

Markdown saved to: .../output/visibility_playbook.md

---

Our Kiro Workflow (Repeatable Pattern)

1. Write/adjust spec → commit
2. Kiro generates/updates stubs & tests
3. Run hooks (format, lint, typecheck, test)
4. Refine via conversational prompts (we shared practically all Kiro outputs with our AI coach and kept prompts tight to avoid drift)
5. Demo run (CLI prints Top-5 and exports Markdown)

This loop is easy to teach and review—a big plus for hackathon judges.

---

Challenges (and Constructive Feedback for Kiro)

Kiro is powerful and already tied into our AWS workflow—huge win. We also hit real-world edges that, if improved, would make Kiro even better:

1. Spec tunnel vision & duplication: New specs sometimes spawned duplicate files instead of reusing existing ones → repo bloat.
2. Inconsistent naming: Parameter names could drift; consistent naming templates would help.
3. Session transitions: On session switches, context could vanish—continuity needs strengthening.
4. Auto-actions without checkpoint: After certain CLI actions, Kiro ran ahead without a user confirm step; a pre-execution prompt would save time.
5. Overload crashes & history loss: When overloaded, Kiro could crash and lose chat history; better recovery would reduce ambiguity.
6. Forgetting despite steering files: At times, Kiro didn’t leverage existing repo context and created duplicates.
7. Silent background work: Occasionally ran without visible “working” state; a consistent status channel would help.
8. Partial prompt execution: Sometimes only the first instruction of a multi-step prompt was executed.
9. Non-actionable intent: Kiro declared intent to implement, but no change followed—clear next-step guidance would help.
10. Access continuity: Clear, predictable access beyond trial periods keeps teams committed to Kiro long term.

We’re sharing this list to be helpful—we like Kiro and want it to win.

---

What We Learned

• Specs are force multipliers. A crisp spec makes AI pairing predictable.
• Determinism beats “wow.” Judges and users prefer reproducibility over fragile complexity.
• Evidence > claims. One run should make the value obvious—URL in, five actions out.

---

What’s Next

• Ship the VC as a complete MVP (persona outputs + robust export) and begin field tests with 4 early adopters in Munich (incl. Oktoberfest hosts).
• Packages + Stripe for the first 100 customers in our home market.
• Admin Audit Dashboard (GDPR transparency, anomaly detection, export).
• Persona-adaptive prompt templates (A/B test messaging).
• Forecasting expansion (evaluating Gemini / LLaMA integrations).

---

Try the Demo Locally

npm install
npm run build
node dist/cli/index.js
# outputs Top-5 actions and writes output/visibility_playbook.md

---

Closing

Kiro helped us turn a well-defined spec into a working product with a clean story: paste a URL → get five decisive actions and a one-page plan. That’s the kind of leverage small hospitality teams need—and the kind of repeatable development loop we’ll keep using as we scale Matbakh’s Visibility Coach.

From Spec to Shipping in Hours: How Kiro Helped Us Build Matbakh’s Visibility Coach