Lab B — `.kiro/` config map

Before this: Prove policy offline (Lab A) proved policy passes before any cluster exists.

This lab proves the spine claim it owes: the configuration in the repository is what makes a thin prompt safe. Everything below is an index of config on disk — not a live KiroKiro
Amazon's agentic IDE — runs vibe or spec sessions against the factory's `.kiro/` steering, skills, and hooks. session. Tall maps live on sibling pages so this hub stays scannable; Lab C’s thin prompt draws on the same files.

The .kiro/ contract in jajera/kiro-eks-argocd-migration is layered: steeringsteering
Always-on and conditional markdown in `.kiro/steering/` that encodes naming, overlays, clusters, and archetypes a reviewer would otherwise carry in their head., skillsskills
Ordered procedures under `.kiro/skills/` (for example `add-app`) so the agent follows one sequence instead of inventing a tree each time., hookshooks
Hard gates in `.kiro/hooks/` that refuse forbidden paths, bad PDBs, and live cluster apply from chat., and the agentagent
Kiro agent bundle (for example `eks-migration`) that loads steering and skills so one thin prompt activates the contract. bundle.

The .kiro/ tree

Frames below are rendered config views — not a live Kiro IDE montage.

Repo layout shows platform trees beside the Kiro contract on disk.

The Kiro tree holds steering, skills, hooks, agent, MCP, and specs.

Steering

Steering is markdown that loads into context automatically, so a reviewer’s usual knowledge — naming, layout, required fields — is present before the agent writes anything.

Always-on facts load every turn; heavy archetype rules wait for matching paths.

always files stay cheap; conditional files load only when their path pattern is in play.

project-profile is always-on: clusters, region, and policy engine keys.

Archetypes load only when apps/** paths enter the conversation.

Archetypes load only when apps paths enter the conversation.

File	Mode	Purpose	Map
project-profile.md	always	Clusters, region, owner, policy engine — every other file defers here	Project profile map
gitops-conventions.md	always	Argo CD + Kustomize base/overlay layout	—
workload-archetypes.md	conditional (apps/**)	Five archetypes, required inputs, hardening	Workload archetypes map
identity-and-secrets.md	conditional (apps/**)	Per-workload IAM (Pod Identity) and secrets	—
policy-validation.md	conditional (apps/**, policies/**, scripts/**)	Which local checks apply and when	—
ci-workflows.md	conditional (.github/**)	What each CI workflow checks	—

See steering. Open a Map link for the full picture; empty Map cells wait on the same treatment.

Skills

A skill is an ordered procedure. Facts belong in steering; procedures belong in skills.

Skill	Trigger intent	Key behavior
add-app	Add a new app, create a service, deploy something new	Scaffolds base plus both overlays; asks for archetype and required fields first
migrate-workload	Migrate off EC2/ECS/Compose	Eight gated phases; a failed gate blocks the next
promote-app	Promote / ship to prod	Confirms dev Synced/Healthy, then copies the verified digest
manage-clusters	Bootstrap, ApplicationSet, add-ons	Edits bootstrap/ and clusters/, not app trees

See add-app, migrate-workload, promote-app, and manage-clusters. Deep skill maps can land beside the steering maps later — same hub pattern.

Note

Four skills and eight hooks are a starter set, not a closed catalog. Keep, drop, or add procedures and gates as your reviews need — the layering (steering → skill → hook) stays.

add-app orders base, then both overlays, then validation.

migrate-workload keeps discovery ahead of scaffold and forbids skips.

Hooks and the PDB scar

Hooks are hard gates in .kiro/hooks/ — IDE-level, not agent-level. That is why eks-migration names no hooks: they enforce anyway.

Category	Hooks	Fires on
Shell gate	block-infra-commands	preToolUse on shell
Scaffold checks	validate-app-scaffold, validate-infra-scaffold	fileEdited under apps/** or platform trees
Build / policy	kustomize-build-check, kustomize-build-check-on-edit, gator-test-on-create, gator-test-on-edit, policy-validate	create/edit on kustomization or workloads

See hooks.

Eight hooks in three categories — shell deny, scaffold checks, build and policy.

Hooks enforce scaffold checks, policy checks, and the shell deny list.

validate-app-scaffold encodes the PDB scar: PDBPDB
PodDisruptionBudget — limits voluntary disruptions; the factory scar requires replicas >= 2 when minAvailable is 1. minAvailable: 1 is only valid when replicas >= 2.

PDB scar: replicas 1 must not keep minAvailable 1.

The shell gate denies mutating cluster, cloud, or registry commands before they run. Changes reach a cluster only through Argo CDArgo CD
GitOps continuous delivery controller that syncs Kubernetes manifests from Git into the cluster. after a human merges. Shape: when.type: preToolUse, when.toolTypes: ["shell"], then.type: askAgent demanding ACCESS DENIED for mutating families while allowing kustomize build, gator, and read-only local commands. Full deny/allow lists live in block-infra-commands.kiro.hook.

Agent, MCP, specs

Source: .kiro/agents/eks-migration.json

{
  "name": "eks-migration",
  "description": "Migrates workloads onto EKS managed by Argo CD, following the gated migration workflow.",
  "welcomeMessage": "EKS migration agent. Tell me what to migrate, for example: migrate the app in ./src to EKS.",
  "tools": ["*"],
  "resources": [
    "file://.kiro/steering/*.md",
    "skill://.kiro/skills/*/SKILL.md"
  ]
}

The resources array bundles every steering file and every skill by glob. Hooks stay out of this JSON on purpose — they are IDE-level.

eks-migration wires steering and skills into one session bundle.

MCPMCP
Model Context Protocol adapters — docs MCP stays on; live cluster adapters stay off until a human intentionally enables them. servers:

Server	Purpose	Default state
aws-knowledge	AWS docs search and regional availability	On
filesystem	Read/write access to this repo	On
eks	Live EKS reads	Off until credentials; --read-only
kubernetes	Live cluster tools	Off until credentials; non-destructive only

MCP keeps docs on; live cluster adapters stay off until creds exist.

Specs under .kiro/specs/<feature>/ hold requirements.md, design.md, and tasks.md as reviewable history (initial-project-setup, gatekeeper-admission upstream).

Specs persist requirements, design, and tasks as project history.

How the layers connect

Prompt to sync: skills generate, hooks enforce, humans approve, Argo CD applies Git.

skills generate → hooks enforce → humans approve.

Tradeoff

Choice: steer with always for cheap global facts and fileMatch for heavy archetype rules. Alternative: load every steering file every turn. Reason: conditional inclusion keeps the context window clean during unrelated cluster work without losing web-service contracts when apps/** is in play.

If a scaffold gets blocked here, the PDB scar is the usual cause — see Known scars: the PDB scar at replicas 1 for the fix.

Next: Project profile map — deep dive on the always-on keys Lab C inherits.