Day 1
The First Morning
Day 1
Maryland
The First Morning
A new engineer sits down. The chair is wrong, the monitors are wrong, the desk still has someone else’s sticky notes on the rim. Somewhere in Slack a welcome message has already fired. Cheerful. Automated. Nobody reads it. The real onboarding hasn’t started because it lives in someone’s head. Several someones, and they’re all in a meeting until noon.
I have watched this happen maybe a hundred times across four companies, and it goes roughly the same way each time. Someone pastes a link to a Confluence page last edited in 2021. Someone else says, “Just shadow me for a few days.” By Wednesday, the new person has seventeen browser tabs open, drowning in context that manages to be overwhelming and incomplete at the same time.
I wanted to build something different. I built a Kiro power, a custom onboarding power that gauges what the new engineer already knows, walks them through the codebases they’ll actually work in, pulls a real task off the project board, and assigns it to them. When they sit down to work on that task inside Kiro, they encounter spec-driven development for the first time. Not through a lecture. Through doing.
Powers run in the Kiro IDE. If your team uses Cursor or Claude Code, the prompts and thinking in this article can still inform how you structure onboarding, but the power itself, the packaging, and the dynamic activation and the MCP integration, need Kiro.
What a Kiro Power Actually Is
If you haven’t used Kiro yet, the word “power” probably sounds like marketing. It’s not. A power bundles three things into a single installable unit: a POWER.md steering file with frontmatter keywords that tell Kiro when to activate it, an mcp.json that configures the MCP servers your agent can call, and an optional steering/ directory with workflow-specific markdown files that load on demand. You can also wire in hooks, automated tasks that fire on IDE events like file saves.
The structure looks like this:
onboarding-power/
├── POWER.md # Frontmatter + agent instructions
├── mcp.json # MCP server config (Jira, Linear, etc.)
└── steering/
├── skill-assessment.md
├── codebase-walkthrough.md
└── first-task.md
You install a power with one click, and Kiro activates it dynamically based on keywords in your conversation. Mention “onboarding” or “new engineer” and the power loads its steering and MCP tools into context. Move on to something else, and it deactivates, freeing up the context window. Kiro only loads what’s relevant at any given time.
The launch partners give you a sense of scope: Stripe, Neon, Supabase, Figma, Netlify, Datadog, Terraform, and Aurora. Each one packages the vendor’s best practices and MCP tools into something the agent can use without you reading through their docs first. But the interesting part, the part this article digs into, is that anyone can build a power. Including you. For your team. For a use case no vendor will ever build because it’s specific to your codebases, your infrastructure, and your onboarding process.
What We Mean When We Say Onboarding
Most onboarding documents read like they were written by a committee that never met. Where the repos live. How the CI pipeline works. A diagram no one has updated because updating it would require understanding it, and understanding it would require talking to someone who left two years ago.
Information overflows. Sequence doesn’t exist. You hand a new engineer everything at once, architecture docs and style guides and access requests and Jira boards, and call it empowerment. What you’ve actually done, without meaning to, is build a wall out of browser tabs.
The POWER.md at the heart of this onboarding power steers the agent through a different approach. Instead of dumping everything up front, it moves through phases: assess the engineer’s skills, orient them in the specific codebases they’ll touch, then hand them a real task. Each phase loads its own steering file, so the context stays focused on what the engineer needs right now, not everything they’ll eventually need to know.
The Questions That Matter
Before the power generates a single task, it needs to know what the new engineer already carries. Not their resume. Their operational knowledge, the stuff that doesn’t fit on a LinkedIn profile. Someone who has “3 years of React experience” and someone who has debugged a stale closure in a useEffect cleanup function inside a context provider that re-renders on route change occupy completely different positions on the learning curve. That gap decides whether the onboarding starts at chapter one or chapter four.
The skill-assessment.md steering file contains the prompt that drives this phase:
You are an onboarding architect for a software engineering team.
Before generating any tasks or documentation, conduct a structured
technical interview with the new team member. Ask questions in
rounds of three, waiting for responses before proceeding. Cover:
1. Languages and frameworks they have shipped production code in
(not tutorials, not side projects. Production, with users)
2. Their experience with the specific infrastructure: AWS services,
CI/CD tooling, containerization, IaC
3. How they debug. Not philosophically, but mechanically. What do
they open first. What do they type.
4. Their experience with the team's domain (in this case: media
streaming, content delivery, rights management, ML inference
pipelines)
Do not summarize their answers back to them. Do not praise them.
Store the answers as a structured knowledge profile and say
"Ready to build your onboarding plan" when the interview is
complete.
I want to call out the phrasing “not tutorials, not side projects. Production, with users.” That line is doing real work. It gives the model permission to treat the distinction as meaningful. Because it is. I have interviewed people who listed Kubernetes on their resume and meant they completed a tutorial on Minikube once. The prompt needs to smoke that out early or whatever the power generates next will be calibrated wrong.
And here’s the part that makes this worth the setup: the power knows your codebases. Kiro’s agent has access to the project’s file structure, the steering files your team has already written (product.md, structure.md, tech.md), and whatever MCP servers you’ve configured. So when the interview reveals that the engineer has never worked with event-driven architecture but has deep REST API experience, the codebase-walkthrough.md steering file skips REST and focuses on the event bus. If your team owns three services, a shared library, and an ML inference pipeline, the walkthrough covers exactly those, not a generic “welcome to microservices” tour. Every onboarding I’ve built before this was one-size-fits-most. This one reshapes itself around the person and the code they’ll actually commit to.
Building the Plan from the Profile
Now the agent has something to work with. A profile, shaped by the interview, showing where this particular person sits relative to the codebases they’re walking into. The next prompt, still driven by the power’s steering, bridges the distance between what they know and what the team needs them to know:
Using the knowledge profile from the interview, generate a
structured onboarding plan for this engineer. The plan must:
- Skip any topics where the engineer demonstrated production-level
competence
- Prioritize the largest knowledge gaps that block independent work
- Structure tasks as a dependency graph, not a flat list
- Each task must include: a description of WHY this knowledge
matters to the team (not generically, but specifically, what
breaks if they don't understand it), acceptance criteria that
can be verified by the engineer themselves without asking
anyone, and estimated time
The plan should have three phases:
Phase 1: Environment and access (things that block everything)
Phase 2: Architecture comprehension (read, don't build)
Phase 3: First contribution (build, ship, close a ticket)
Output as a structured plan with tasks and subtasks.
The phrase I care about most here is “what breaks if they don’t understand it.” Engineers learn faster when the stakes are concrete. “Understand our caching layer” tells them nothing about consequences. “If you deploy without understanding the caching layer, you will serve stale content recommendations to 14 million subscribers for up to six hours,” gives them a reason to pay attention. I have seen the second version cut ramp-up time in half because people stop skimming when the consequences are specific to them.
Wherever this plan lives, it needs to function as a dependency graph, not a grocery list. Phase two depends on phase one, phase three depends on phase two, and skipping ahead makes the whole thing wobble.
Connecting to the Work
Phase three is where most onboarding quietly falls apart. The new engineer has read the docs, set up their environment, attended the architecture walkthrough, nodded at the right moments. Then someone says “just pick up a ticket” as if the Jira board were a fruit stand and not a minefield of implicit context, undocumented dependencies, and tickets that say “fix the thing” with no further elaboration.
I had a new hire once spend three days on a ticket that turned out to be blocked by an infrastructure change nobody had mentioned. Three days. He didn’t ask for help because he thought struggling was the point. That’s what “just pick up a ticket” gets you.
The onboarding power’s mcp.json configures a connection to your project management system. Jira, Linear, Asana, whatever your team uses. The first-task.md steering file tells the agent how to select and assign the right ticket:
Connect to the project management system via MCP.
Query for tickets that meet ALL of the following criteria:
- Tagged as "good-first-issue" or complexity: low
- In the current sprint or backlog (not blocked, not stale)
- Touches a service or module covered in Phase 2 of the
onboarding plan
- Has clear acceptance criteria already written
- Does not require access to production infrastructure
- Is not on the critical path for any current milestone
From the matching tickets, select the one that provides the
highest learning value based on the new engineer's knowledge
profile. "Learning value" means: it exercises a skill they
partially understand but haven't yet applied in this codebase.
Assign the ticket to the engineer and present it with:
- The original ticket description
- Pointers to the specific files and functions they'll modify
- The tests they'll need to write or update
- The PR conventions for this team
Then instruct the engineer to create a Kiro spec for this
ticket before writing any code.
Look at what the selection criteria exclude. “Not on the critical path” means the new engineer can move at learning speed without someone checking on them every hour. “Does not require access to production infrastructure” means they won’t sit idle for three days waiting on an IAM request in someone’s approval queue. These constraints serve a psychological purpose more than a technical one. The first task has to be completable. Fully, independently, without anyone riding in to rescue them. That’s how you build confidence.
And look at that last line: “instruct the engineer to create a Kiro spec for this ticket before writing any code.” Spec-driven development enters the picture right there, through the work itself, on the first task.
The First Spec
The engineer opens the ticket in Kiro. The power has already pointed them to the files, the tests, the PR conventions. Now it tells them to create a spec.
In Kiro, a spec follows a three-phase workflow: requirements.md captures user stories and acceptance criteria in EARS notation, design.md documents the technical approach and architecture decisions, and tasks.md breaks the implementation into discrete, trackable steps. The agent walks through each phase, and the engineer reviews and edits at every stage before moving forward.
For a new engineer, this process does double duty. They’re learning the feature they’re about to build, yes. But they’re also learning how the team works. Spec-driven development makes you think before you code. Your decisions get written down instead of evaporating into a chat log. Other people can review your thinking, not just your code. The new engineer picks all of that up by doing it, on a real ticket, in their first week.
I’ve watched engineers go through this flow and come out the other side understanding what they built and, more importantly, why the team structures work this way. The spec becomes documentation of their thinking. Their first PR carries context that most first PRs lack entirely.
Closing the Loop
The engineer ships the PR. The power’s steering has one more phase:
The engineer has completed their first ticket. Generate a
post-completion review that:
1. Identifies which knowledge gaps from the original profile
were exercised and can now be marked as addressed
2. Recommends the next three tickets in ascending complexity,
using the same selection criteria but relaxing one constraint
(allow slightly higher complexity, or allow a different
service area)
3. Updates the onboarding plan to reflect progress
4. Flags any areas where the engineer's spec or PR suggests a
misconception that should be addressed before it compounds
Do not frame this as feedback. Frame it as a map update.
"You are here now. Here is what's next."
“Map update” instead of “feedback” is the choice I keep coming back to. People hear “feedback” and brace for judgment, even when you don’t mean it that way. But telling someone “you were here, now you’re here, and here’s what’s next” just sounds like navigation. That framing changes how people receive it, and I’ve found it changes how honestly they report what they don’t understand.
The next tickets get assigned. Each one slightly harder, slightly broader in scope, each one building a new spec before any code gets written. By the third or fourth ticket, spec-driven development has stopped feeling like a process and started feeling like how they work.
What You’ve Actually Built
Forget the prompts for a second. You’ve built an onboarding that starts by figuring out what the engineer knows, orients them in the codebases they’ll actually touch, and then pulls a real task off the board and hands it to them with instructions to write a spec before they write a line of code. All of it steered by a POWER.md and a handful of markdown files in a steering/ directory.
I built this in Kiro because powers give the process a spine. The steering files keep each phase focused, the MCP connection to your project board pulls real tickets instead of fake exercises, and Kiro’s spec workflow turns the first task into a lesson in how the team operates.
Think about the engineer three weeks from now. Editing files across multiple services, moving fast, creating specs before they code, because that’s what they did from day one. Not because someone told them the codebase was simple, but because they earned the context by working through it, one spec at a time.
Each piece of the onboarding modifies the next. The skill assessment shapes the codebase walkthrough, which shapes the first task selection, which shapes the first spec, which shapes how the engineer understands what this team builds and why they build it this way. Get the order wrong, and it all falls apart. Get it right and three weeks feels like three months of ramp-up compressed into something that actually holds together.
By Joshua McDonald on April 9, 2026.
Exported from Medium on August 26, 2026.
Reader discussion