Kiro: Field Engineering Workshop for Spec-Driven Factory Software

Educational engineering purpose only. This is a software architecture exercise and not process-release advice.

Workshop purpose

This two-hour professional developer workshop teaches engineers how to use Kiro as the primary AI engineering service for building production-shaped software from scratch. The example project is a TypeScript React application for factory machinery risk triage, inspired by semiconductor-fab control dashboards: typed fixtures, live simulated telemetry, risk scoring, expandable evidence panels, SVG visuals, and advisory-only operating language.

The workshop is intentionally technical. It is not a business overview and it is not a slide-only session. Participants will use Kiro to create project context, generate specs, implement code, create tests, automate quality checks with hooks, and correct type-safety drift before it becomes expensive rework.

Target audience

● Professional developers building internal engineering applications.

● Field engineers who need to turn machine domain rules into robust software.

● Technical leads who want repeatable AI-assisted development standards.

● Developers who have seen AI tools rush through untyped React code and want a guard-railed workflow.

Learning outcomes

By the end of the workshop, participants can:

● Use Kiro steering files to encode TypeScript, React, accessibility, and factory-safety standards.

● Use Kiro specs to convert a vague engineering feature into requirements, design, and implementation tasks.

● Build a typed React project from scratch with deterministic fixture data and simulated live updates.

● Use agentic chat for focused implementation without abandoning spec traceability.

● Use hooks to run type checks, lint-style inspections, and documentation updates on file events.

● Diagnose type declaration false-starts and correct them with domain models, union types, strict props, and typed state.

● Keep engineering software advisory-only when it relates to machinery, routing, quality, or production approvals.

Two-hour agenda

Demo project architecture

The workshop project is a local-only React application:

factory-risk-portal/
├── .kiro/
│   ├── steering/
│   │   ├── product.md
│   │   ├── tech.md
│   │   └── structure.md
│   └── hooks/
│       ├── typecheck-on-save.json
│       └── review-react-change.json
├── src/
│   ├── App.tsx
│   ├── components/
│   │   ├── Header.tsx
│   │   ├── RiskBoard.tsx
│   │   ├── Sparkline.tsx
│   │   └── MetricCard.tsx
│   ├── data/
│   │   └── fixtures.ts
│   ├── domain/
│   │   └── risk.ts
│   ├── types.ts
│   ├── styles.css
│   └── main.tsx
├── index.html
├── package.json
├── tsconfig.json
└── README.md

System design rationale

● Intent is separated from implementation. The .kiro/steering files define how the team wants React, TypeScript, safety language, and folder structure to behave before any large code generation begins. This prevents the AI from treating a safety-sensitive factory dashboard as a generic demo page. In field engineering, domain terms such as risk, hold review, route limit, and advisory status must be modeled consistently because operators and owners read those labels as action cues.

● Domain models sit before UI components. The workshop creates types.ts, fixtures.ts, and risk.ts before rendering the dashboard. That order is deliberate: the UI should consume stable contracts rather than inventing implicit object shapes in JSX. When a developer asks Kiro to generate views too early, it may infer stringly typed props, permissive arrays, or any-like structures. The domain-first structure lowers false starts and makes sorting, filtering, and charting deterministic.

● The project remains local and advisory-only. The lab avoids live equipment calls, automation commands, and backend integrations. The point is to teach Kiro’s software engineering workflow, not connect to machinery. This is a safer and more portable classroom design. It also keeps the architecture testable: fixture data, simulated update loops, and pure risk functions can be reasoned about without network flakiness, credentials, or operational approvals.

The type declaration headache: what happened and how to avoid it

Yes, React projects can produce headaches when an AI assistant rushes into component generation without a type contract. The most common false-start is that the assistant writes a beautiful JSX table first, then retrofits types after state, sort keys, callbacks, and fixture objects already exist. That usually creates mismatched string actions, broad Record<string, unknown> sorting, loosely typed children, and event handlers that rely on inference rather than shared domain types.

In this workshop, the fix is to make Kiro understand standards before implementation:

● Steering files explicitly require strict TypeScript, no any, domain union types, typed props, and typed fixtures.

● The spec requires a data model and component boundary before UI tasks begin.

● Hooks run type checks and ask Kiro to review risky changes whenever TypeScript or React files are saved.

● Prompts instruct Kiro to pause when a type is unclear instead of guessing.

● Sorting keys are represented as a union type, not arbitrary strings.

● Machine recommendations are represented as a union type, not free-form action labels.

Example standard to give Kiro

# TypeScript standard

- Use strict TypeScript.
- Do not use `any` or implicit object shapes.
- Create domain types before UI components.
- Represent action labels as union types.
- Represent tab names and sort keys as union types.
- Type React props explicitly.
- Prefer pure functions for risk logic and chart coordinate calculations.
- If a type is ambiguous, ask for the missing contract or create a named type with comments.

Kiro capability map used in the workshop

Facilitator preparation

● Install Kiro and open an empty folder named factory-risk-portal.

● Confirm Node.js and npm are available.

● Prepare a terminal for npm create vite@latest, npm install, and npm run dev.

● Decide whether participants will use the same fixture values or author their own machine examples.

● Keep the project offline: no production APIs, no equipment commands, no credentials.

Instructor script

Opening statement

Today we will use Kiro to build like a senior field-engineering team: specify first, type the domain, implement in small steps, automate review, and preserve human approval boundaries. The goal is not to make AI write the most code fastest. The goal is to make Kiro produce code that matches engineering intent, can be reviewed, and does not create unsafe operational ambiguity.

When participants ask about untyped React output

Tell them: if Kiro starts generating untyped JSX, stop and add steering. Then ask Kiro to extract the implicit shapes into named domain types before continuing. A well-steered Kiro session should produce Action, Tool, SortKey, and component prop types before it builds the live board. If the model guesses, tighten the spec. If it repeats a bad pattern, add a hook or steering file.

Success criteria

The completed lab should have:

● A working TypeScript React app.

● Domain types for machinery records, status actions, tabs, and sort keys.

● Search and sort behavior.

● Simulated live updates.

● SVG charts without charting dependencies.

● Advisory-only labels and footer.

● Kiro steering files.

● Kiro hook configuration.

● At least one unit-testable pure function.

● A README with operational boundaries.

---

facilitator notes: field engineering framing

This workshop should be facilitated as an engineering-quality exercise, not as a generic AI coding demonstration. The factory machinery context is useful because it forces participants to think about typed records, signals, thresholds, evidence panels, and human approval boundaries. The facilitator should repeatedly connect software design choices to real field conditions: noisy sensors, incomplete route history, stale SPC windows, naming inconsistencies, and the cost of ambiguous UI language.

When presenting Kiro, emphasize that the service is not being used to replace senior engineering judgment. It is being used to preserve judgment in repeatable artifacts: steering files, specs, typed models, hooks, review prompts, and testable functions. The strongest learning point is that Kiro performs better when the team gives it a technical system for working, rather than just a large request for code.

Instructor timing and pacing guide

0:00-0:10 — Orientation

Instructor objective: establish the safety and quality boundaries before any coding begins.

Talk track:

● The lab project is local-only.

● No production API, PLC, MES, FDC, APC, dispatch, or equipment endpoint is connected.

● Every recommendation is advisory and reviewable.

● TypeScript is part of the safety boundary because it prevents unsupported states from silently entering the UI.

Common participant question: “Why are we spending time on steering instead of coding?”

Answer: Because without persistent standards, the assistant may optimize for visible output rather than engineering correctness. Steering files are the equivalent of posting coding standards, safety language, and architecture rules directly inside the workspace context.

0:10-0:25 — Steering

Instructor objective: show that Kiro can be guided before implementation.

Demo action: create the three steering files live and ask Kiro to summarize its obligations.

Expected Kiro behavior: it should mention strict TypeScript, local fixtures, no backend calls, advisory-only wording, and project structure.

Warning sign: if Kiro immediately proposes a large component implementation, pause and instruct it to produce a task plan only.

0:25-0:45 — Spec

Instructor objective: turn a feature idea into a reviewable engineering artifact.

Demo action: ask Kiro to create a spec with requirements, design, and implementation tasks.

Expected Kiro behavior: it should create acceptance criteria for search, sort, expand/collapse, simulated updates, accessibility, and advisory-only labels.

Facilitator tip: ask participants to identify one acceptance criterion that would catch an unsafe implementation. Good answers include: “No action label implies direct equipment command,” “risk is shown with text not just color,” and “sort keys are typed.”

0:45-1:15 — Build core app

Instructor objective: implement in the correct sequence: types, fixtures, domain logic, visual components, then app shell.

Demo action: accept Kiro edits task by task. Avoid accepting a full application rewrite unless the code is easy to inspect.

Warning sign: if Kiro generates action: string, sortKey: string, or any, stop and ask it to repair the type model before continuing.

1:15-1:30 — Charts and live updates

Instructor objective: demonstrate useful front-end logic without adding unnecessary dependencies.

Demo action: build SVG sparklines and a larger trajectory chart. Show how coordinate math is isolated inside typed components.

Discussion point: not every visualization needs a library. For small engineering dashboards, inline SVG can be transparent, auditable, and sufficient.

1:30-1:45 — Hooks

Instructor objective: make quality checks automatic.

Demo action: create hooks for type checking and Kiro review.

Key message: hooks should not be used to make operational decisions. They are development workflow automation only.

1:45-1:55 — Hardening

Instructor objective: show Kiro as reviewer, not just author.

Demo action: ask Kiro for a prioritized fix list first. Implement only safe, small changes.

Common issue: Kiro may suggest more refactoring than the remaining time allows. Teach participants to defer larger changes into a backlog.

1:55-2:00 — Wrap

Instructor objective: consolidate reusable workflow.

Wrap-up questions:

● Which steering rule prevented the most rework?

● Which type declaration would have failed if it had been left as string?

● Which hook would you add for your own team?

● What project-specific factory terms should be encoded as union types?

Deep dive: why Kiro should be used spec-first in machinery applications

Machinery-facing applications have a hidden failure mode: a UI can look polished while its underlying operational semantics remain ambiguous. For example, a button labeled “HOLD” could mean “show hold recommendation,” “create a hold request,” “send a dispatch hold,” or “command equipment stop.” A spec-first Kiro workflow forces the team to define behavior before implementation. The spec becomes the boundary between what the application displays, what it calculates, what it explicitly does not do, and what requires human approval.

The facilitator should make this point concrete: Kiro can generate code quickly, but a field engineering team needs explainable software. The spec should answer what data exists, what state changes locally, what recommendations mean, what is out of scope, and what acceptance criteria prove the boundary. This mirrors engineering change control, where a proposed change must define scope, expected result, and verification before release.

Expanded answer: type declaration headaches and Kiro standards

The most effective way to avoid TypeScript false-starts is to make the type system part of the promptable architecture. Kiro should be told that types are not cleanup work; they are the first implementation artifact. In the workshop, every risky value category becomes a named type:

● Recommendations become a Recommendation union.

● Tabs become a TabKey union.

● Sortable metrics become a SortKey union.

● Risk display classes become a RiskTone union.

● Machine rows become a MachineRecord type.

● Sensor mappings become a HealthLink type.

This design addresses the exact failure mode many React projects face: the assistant renders a table first and infers everything as loose strings. Once loose strings spread into state and props, later type cleanup becomes broad and noisy. The workshop reverses the order: model first, UI second.

Facilitator checklist before running the workshop

● [ ] Confirm Kiro opens the workspace and can read .kiro/steering.

● [ ] Prepare a backup copy of the three steering files.

● [ ] Prepare a backup copy of the domain types.

● [ ] Confirm the local machine can run npm create vite@latest.

● [ ] Confirm participants understand that no real factory system is connected.

● [ ] Prepare a simple explanation of risk thresholds.

● [ ] Prepare a fallback static fixture dataset if internet access is limited.

● [ ] Decide whether hooks will be created live or copied from the guide.

● [ ] Keep final hardening time protected; do not let implementation consume the last 10 minutes.

Facilitation anti-patterns to avoid

● Do not ask Kiro to “build the whole app” as the first instruction.

● Do not accept generated code that uses any as a placeholder.

● Do not let CSS polish take priority over typed state and domain logic.

● Do not introduce external APIs during the workshop.

● Do not let recommendation labels sound like direct commands.

● Do not let hooks run destructive shell commands.

● Do not let Kiro refactor the entire app in the final minutes.

Suggested participant exercises if time remains

Exercise A — Add a new recommendation safely

Ask participants to add ENGINEERING REVIEW as a recommendation. They should update the union type, add one fixture record, verify display behavior, and confirm sorting still works.

Exercise B — Add a new sortable metric

Ask participants to add siteRangeNm to MachineRecord and make it sortable. They should update fixtures, the SortKey union, metric labels, and expanded detail display.

Exercise C — Extract a large component

Ask participants to move the Live Risk Board into components/RiskBoard.tsx with explicit props. They should avoid passing the entire app state when only a few values are needed.

Exercise D — Improve the final review hook

Ask participants to customize the agent hook for their team’s standards, such as naming conventions, design-system classes, security review wording, or code-owner tags.

Suggested backlog after the workshop

● Add unit tests for getRiskTone, filterMachines, sortMachines, and simulated updates.

● Add a component test for expand/collapse behavior.

● Add a fixture validation script.

● Add an architecture decision record for advisory-only scope.

● Add a local JSON import path for participants who want to load alternate sample data.

● Add an accessibility pass for keyboard order and screen-reader labels.

● Add a data dictionary for machinery metrics.

● Add a changelog entry template for future feature changes.

Instructor closing summary

The core practice is simple: tell Kiro how your engineering team works before asking it to produce code. Then ask for a spec, implement in small typed steps, automate checks, and review language as carefully as logic. This approach is slower than a one-shot prompt in the first five minutes, but faster over the full engineering lifecycle because it prevents type drift, unsafe wording, and unreviewable implementation shortcuts.

---

Additional facilitator guidance: depth modules for mature engineering teams

Module A — How to frame Kiro as an engineering co-worker, not an autopilot

Kiro should be introduced as a structured software engineering assistant that can help create specifications, code, tests, documentation, and review notes. In a machinery or factory engineering context, the facilitator should repeatedly emphasize that Kiro is not approving operational action, not replacing an equipment owner, and not creating a direct control loop. The value is in accelerating controlled software development: requirements capture, type-safe implementation, repeatable review, and documentation that a professional team can inspect.

A practical framing is: Kiro accelerates engineering intent; it does not own engineering authority. Developers remain responsible for architecture, safety boundaries, data contracts, and production readiness. This framing is especially important for teams that work near physical machinery, because a UI recommendation can be misread as an instruction if language is not carefully governed.

Module B — Recommended instructor demo narrative

Use the following demo storyline:

● A production engineer has a recurring issue: factory risk dashboards are built quickly but become hard to maintain because the first version mixes domain rules, UI rendering, and untyped data objects.

● The team decides to use Kiro, but they do not start by asking for a full app. They first create steering files that define TypeScript rules, advisory wording, and folder boundaries.

● The team asks Kiro to create a spec. The spec becomes the agreement between the developer, reviewers, and future maintainers.

● Implementation begins with domain types and fixture data, not CSS or charts.

● Kiro generates components in small steps. Each step is reviewed for type safety and advisory wording.

● Hooks are added so the project keeps checking itself during the workshop.

● The team ends with a working app plus reusable prompts and standards.

This narrative makes the workshop feel like engineering work rather than a chatbot demonstration.

Module C — What to say when Kiro generates too much code

If Kiro generates a large unreviewable implementation, pause the session and demonstrate the correction pattern:

Stop. Break this implementation into smaller tasks. First create the domain types and fixture data only. Do not create UI components until the types are approved.

Explain to participants that this is not a failure; it is normal AI-assisted development. A good engineer redirects the tool back to traceable tasks. The key is to avoid accepting a large diff that mixes data model, rendering, styling, and behavior before it can be reviewed.

Module D — Facilitation checklist for type declaration issues

Use this checklist live when participants hit type errors:

● Is the label a business concept? If yes, make it a union type.

● Is a string used to select a metric? If yes, make it a typed key union.

● Is an array being sorted? If yes, copy it first.

● Is state initialized from a fixture? If yes, type the state explicitly.

● Is a component receiving object props? If yes, create a named props type.

● Is a chart receiving numbers? If yes, type the data array and bounds.

● Is a function testable without React? If yes, move it to a domain file.

● Is Kiro using any or as assertions? If yes, ask it to remove assertions and create proper types.

Module E — Suggested whiteboard architecture

Draw this architecture during the workshop:

Kiro Steering
   ↓
Kiro Spec
   ↓
Domain Types ── Fixtures ── Pure Risk Logic
   ↓                  ↓             ↓
Typed React State ── Components ── SVG Charts
   ↓
Hooks: build check + AI review
   ↓
README + backlog + operational disclaimer

The key message is that the UI is downstream from domain contracts. Kiro performs better when the developer gives it stable architectural rails.

Expanded 2-hour timing plan

0:00-0:10 — Orientation

● Ask participants what usually goes wrong in AI-generated React projects.

● Write the answers on the board: any, too much code, wrong folder structure, untyped props, no tests, unsafe language, hard-to-review diffs.

● State that the workshop solves these problems with Kiro steering, specs, hooks, and typed domain-first development.

0:10-0:25 — Steering workshop

● Create the three steering files.

● Ask Kiro to summarize constraints.

● Make participants intentionally add one strict rule: “If a type is ambiguous, stop and ask or propose a named type.”

● Show how steering prevents repeated prompt boilerplate.

0:25-0:45 — Spec authoring

● Ask Kiro to generate a spec.

● Review the spec like a pull request.

● Add acceptance criteria for search, sort, risk thresholds, expand/collapse, and advisory language.

● Do not begin coding until the spec has a data model section.

0:45-1:15 — Core build

● Build types.ts, fixtures.ts, and risk.ts.

● Ask Kiro to generate focused components.

● Keep the browser open and validate behavior after each small diff.

● If Kiro creates broad strings, pause and correct with union types.

1:15-1:30 — Charts and live behavior

● Add the sparkline and trajectory chart.

● Explain why inline SVG is enough for workshop-grade charting.

● Add simulated updates and verify that state is not mutated.

1:30-1:45 — Hooks

● Add type-check hook.

● Add AI review hook.

● Save a file and observe the workflow.

● Discuss what hooks should and should not do in a controlled engineering environment.

1:45-1:55 — Hardening

● Ask Kiro for final review.

● Implement only low-risk fixes.

● Document known limitations and operational boundaries.

1:55-2:00 — Wrap

● Ask participants to name one steering rule they will use in their own team.

● Ask participants to name one false-start correction prompt.

● Close with the message: “Kiro is most useful when you teach it your engineering system.”

Optional facilitator deep dive: comparing bad and good Kiro prompts

Bad prompt

Build a complete React dashboard for machine risk.

Why it fails:

● No data model.

● No type rules.

● No safety boundary.

● No directory structure.

● No acceptance criteria.

● No limit on dependencies.

Better prompt

Create a spec for a local-only TypeScript React factory risk dashboard. Use strict TypeScript, no backend calls, no charting dependency, typed union labels, typed sort keys, accessible controls, and advisory-only wording. Include requirements, design, implementation tasks, and testable acceptance criteria. Do not write code until the spec is reviewed.

Why it works:

● It defines the process before implementation.

● It forces type contracts.

● It preserves operational boundaries.

● It limits dependencies.

● It creates reviewable artifacts.

Extended success rubric

Score each participant project from 1 to 5:

● Specification quality — Does the spec clearly describe requirements, design, and tasks?

● Type safety — Are domain labels, tabs, sort keys, props, and state typed?

● Component structure — Are data, domain logic, and UI separated?

● Behavior completeness — Do search, sort, expand/collapse, simulated updates, and charts work?

● Safety language — Does the UI stay advisory-only?

● Automation — Are hooks present and useful?

● Reviewability — Are changes small enough for a professional code review?

● Documentation — Does README explain setup, assumptions, and limitations?

Suggested extension backlog for advanced learners

● Add unit tests for getRiskTone, filterMachines, sortMachines, and simulated updates.

● Add a typed evidence-pack object and render it in expanded detail.

● Add URL hash state without full routing.

● Add CSV fixture import as a future enhancement, but keep the workshop local-only.

● Add role-based UI modes as mock state, not real authentication.

● Add a Kiro spec for replacing fixture data with validated data products.

● Add a hook that asks Kiro to update README when public component props change.

● Add a rule that every recommendation must include evidence and owner review text.

Instructor notes on professional tone

Avoid presenting Kiro as magic. Developers trust tools more when the instructor shows boundaries. Say explicitly that Kiro can produce attractive wrong code if the developer gives it vague instructions. The professional skill is prompting plus review plus architecture. In field engineering, this resembles commissioning a machine: define operating envelope, run controlled trials, inspect results, and only then expand scope.