Atlassian uses cookies to improve your browsing experience, perform analytics and research, and conduct advertising. Accept all cookies to indicate that you agree to our use of cookies on your device.
Atlassian uses cookies to improve your browsing experience, perform analytics and research, and conduct advertising. Accept all cookies to indicate that you agree to our use of cookies on your device. Atlassian cookies and tracking notice, (opens new window)
Welcome! This document is a working template. Duplicate it at the start of a new engagement, update the title for your client, and answer the questions inline as you discover details together. Feel free to remove any steps that don't apply to your scope. By the end of the project, this page will serve as a clear, valuable record of what you found, what you built, and the reasoning behind your work.
Scope Note: This guide is specifically tailored for software codebases. If you are helping non-engineering teams (like marketing or sales workflows) adopt AI, the core philosophy still applies, but these specific technical steps will vary.
Many clients invest in AI coding tools with high expectations, but engineering teams often run into frustrating roadblocks:
The AI generates code that violates team conventions.
It can't spin up or test the application locally.
It invents non-existent patterns or inadvertently breaks existing functionality.
Every session feels like starting from scratch, forcing developers to manually re-explain the context over and over.
When this happens, it's easy to blame the AI model itself. However, the issue is almost always a lack of context rather than model capability.
When a human developer joins a team, they naturally pick up the subtle "unwritten rules": the missing setup steps in the README, which services are safe to restart, what a good PR looks like, or which legacy modules to avoid. Because this knowledge becomes second nature to humans, it rarely gets written down. But an AI agent has no way of knowing what isn't explicitly documented.
Our mission comes down to two main goals:
Uncover the implicit knowledge living in people's heads and turn it into structured, machine-readable context.
Package the team's recurring workflows into reusable agent skills.
Building the tools is often the easy part. The real value comes from asking the right questions to uncover what actually needs to be built.
What "AI-Enabled" Means
We aim to bring the agent up to speed across five key capability pillars. Every step in this checklist supports one of these goals:
Run it: The agent can take a fresh repository clone and independently bring it to a verified running state.
Control its data: It can reset the application to a clean slate, seed specific test scenarios, and reliably control external dependencies.
Know what to build: It directly interprets tickets and design assets rather than waiting for someone to copy and paste text into a chat box.
Build it and prove it works: It writes code aligned with local patterns, runs tests, interprets failure logs, and corrects its own errors before asking for review.
Ship it: It creates feature branches, makes clear commits, opens pull requests, and follows the team's established delivery pipeline.
Where Our Work Stops
Our focus is on building the agent-facing layer, while the client retains ownership of their underlying infrastructure.
If the client has an existing CI/CD pipeline, we teach the agent how to interact with it, we don't re-architect their pipeline. If they have a test suite, we enable the agent to run it and interpret results. If a crucial piece is missing entirely, we can build a lightweight version to unblock the agent, but standing up full enterprise infrastructure remains the responsibility of the client or a separate statement of work.
To keep boundaries clear, every task in this guide is categorized:
BUILD Standard work we deliver on every engagement.
BUILD IF MISSING Delivered by us if missing, with long-term maintenance transitioning to the client at handover.
ADVISE We evaluate, recommend, and guide, but execution rests with the client.
A Note on the Templates
Most steps below include a collapsed skill template. These are starting points, not finished skills. Every <angle bracket> is a blank you fill in from your discovery answers, and you should expect to delete sections that don't apply and add ones that do.
All skills follow the same house structure:
.claude/skills/<skill-name>/
├── SKILL.md # main instructions, keep under 500 lines
├── references/ # conventions, schemas, contracts, rule sets
├── examples/ # concrete input/output samples
└── scripts/ # helper scripts the agent can execute
The description field in the frontmatter is the most important line in any skill: it is what the agent reads to decide whether to load the skill at all. Write it with explicit trigger phrases and situations, not a summary of what the skill contains.
The Roadmap of Steps
We recommend working through these steps in order. The sequence reflects true technical dependencies: for example, you can't define how to seed data until you understand where that data lives, and you can't automate pull requests until the application runs reliably.
Every step should be evaluated, but keep in mind that most codebases already have some foundation in place: a partial README, a legacy seed script, or an instructions file that has drifted out of date. Your first job is to discover what exists and verify whether it still works. "Assessed and verified as working" is a great outcome!
Step
Name
What It Achieves
Step
Name
What It Achieves
0
Scoping Interview
Identifies pain points, maps the current workflow, and establishes baseline metrics
1
Map the Topology
Clarifies how the app runs and maps all external connections
2
Get-App-Running Skill
Enables the agent to take a fresh clone to a running, verified app
Taking an out of date repo and updating it.
3
Service Mocking & Data Boundary
Allows the agent to work effectively without relying on live external services
4
Data Seed & Reset Skill
Gives the agent full control over application state
5
Version Control & Delivery
Teaches the agent to branch, commit, push, and open PRs following team norms
6
Requirements Sourcing
Enables the agent to read Jira/Figma and spot conflicts before writing code
7
Planning, Spec & Prototyping
Ensures the agent produces reviewable design plans before coding
8
Implementation
Guides the agent to write clean code that matches existing team patterns
9
Verification & Self-Testing
Empowers the agent to test its own work and fix issues independently
10
Coding Standards & Review
Teaches the agent to perform self-reviews against team guidelines
11
Skill Maintenance
Ensures the tools and skills we build stay valuable after handover
12
Measurement
Demonstrates concrete progress against our original baseline
Focus Areas Based on Engagement Goals
Not every engagement requires equal effort across all 13 steps. Depending on the client's primary goals, your time will naturally shift toward specific steps:
Goal: "Our AI agents write code that doesn't fit our codebase standards."
Primary Focus: Steps 1 through 4 (establishing state control) and Step 10 (coding standards).
Goal: "We want PMs and designers to prototype ideas without waiting on engineering."
Primary Focus: Steps 1 through 3, Step 6 (sourcing requirements), and Step 7 (specs and prototyping).
Goal: "We need to prove to leadership that our AI investment is delivering real value."
Primary Focus: Balanced execution across all steps, with extra care given to Steps 0 and 12 for baseline tracking.
Step 0: Scoping Interview
ADVISE
This step is all about human conversation. The goal is to uncover where the team is actually spending (or losing) time and capture concrete metrics so you can measure your impact in Step 12. Skipping this step risks spending time optimizing workflows that nobody was struggling with!
Tip: Avoid asking broad questions like "What would you like AI to do?" People often reply with high-level ideas they've read about online. Instead, ask grounded questions about their actual experience over the past two weeks.
Discovery Questions
This step can play out as a formal discovery session with the team to uncover the problems/bottlenecks in their development flow, and identify places where AI can assist.
Could you walk me through a single ticket end-to-end, from the moment it's written to when it ships? Who touches it, and where are the handoffs?
Looking at the last two weeks, where did work actually slow down or get stuck?
How are developers currently using AI tools, and where have those tools fallen short or caused headaches?
What does onboarding a new developer look like today? How long does it usually take them to ship their first change?
Establishing Baseline Metrics
Do you currently track DORA metrics (or similar engineering stats)? If so, what do those numbers look like today?
If metrics aren't tracked formally, can we look at Jira history (e.g., ticket lead times) to establish a rough baseline?
What would success look like to team leadership? How would they describe a win in their own words?
Identifying Constraints
Which AI tools are currently approved for use, and are any tools or services strictly off-limits?
What data privacy or security policies apply to sharing code or data with AI models?
Who on the engineering team is most excited about this, who is hesitant, and who will maintain these skills long-term?
Whiteboard Idea: If you have an hour with the team in person or on a virtual whiteboard, map out the lifecycle of a ticket together. Have everyone place dots where they feel the most pain, then vote on the top bottlenecks. This hands-on approach builds quick alignment!
Definition of Done: You can clearly state the client's biggest pain point in their own words and have captured a baseline metric (or documented why a formal metric isn't available yet).
Step 1: Map the Topology
BUILD
Before we can teach an agent how to work in an application, we need to understand how that application fits together. This step is pure discovery, so resist the temptation to start building tools just yet!
Investing time here prevents costly rework later (such as spending days on a database seed script only to realize the core data lives in an external third-party API). It also gives you the clarity needed to validate project timelines and set realistic expectations.
Discovery Questions
How the Application Runs
What are the individual runnable components? (e.g., frontend web, API, background workers, scheduled jobs)
What supporting infrastructure must be running for the app to work? (e.g., PostgreSQL, Redis, RabbitMQ, Elasticsearch)
Which parts run in containers? Is there a working docker-compose setup available?
Is this a monorepo, or do developers need to clone multiple repositories?
What runtime versions are required, and where are those versions defined? (e.g., .nvmrc, mise.toml)
Where the Data Lives(Take extra time here, this directly informs Steps 3 & 4)
Does the application own a primary database that it reads and writes to directly?
When the app makes external network calls, what services does it talk to, over what protocols, and what shape of data is returned?
For each external connection: can it run locally, does a mock exist, or is it cloud-only?
Are there third-party APIs with no local options? (e.g., Stripe, Auth0, Twilio)
Is there an existing data seed or fixture mechanism, and does it currently work?
Environments & Access
What environments exist today? (e.g., local, PR previews, staging, production)
Can a developer run the full stack locally on a laptop, or are remote services required?
Does the client plan for agents to run locally on dev machines, in CI/CD, or in cloud environments?
What credentials or secrets does a developer need, and how are they retrieved?
Are there any security restrictions, VPNs, or network barriers that might impact AI agents?
Pro Tip: The fastest way to answer these questions is to watch an engineer set up the project from scratch, or better yet, attempt to set it up yourself while paired with a developer. A short pairing session reveals all the unwritten steps ("Oh yeah, you have to run that script twice") that your agent skills will need to handle!
Deliverables
A topology document, committed into the client repository so both the team and the agent can read it. This is also the first artifact worth walking through with their engineers, since their corrections are the most valuable output of the step.
# <Application> Topology
Last verified: <YYYY-MM-DD> by <name>
## What This Application Is
<Two or three sentences. What it does, who uses it, and what the pieces are.>
## Runtime Components
| Component | Port | Containerized? | Depends on | Start command |
|---|---|---|---|---|
| <web> | <3000> | yes | <api> | <command> |
| <api> | <4000> | yes | <postgres, redis> | <command> |
| <worker> | n/a | yes | <redis> | <command> |
| <postgres> | <5432> | yes | none | <command> |
Repositories required to run the full stack:
- <repo and why it is needed>
## Integration Points
The most important table in this document. Steps 3 and 4 are scoped from it.
| Called service | Protocol | Runs locally? | Mock exists? | Contract source | Notes |
|---|---|---|---|---|---|
| <Payments> | REST | no | no | <OpenAPI URL> | <third party, sandbox available> |
| <User service> | gRPC | yes | partial | <proto path> | <separate repo, own database> |
## Data Stores
| Store | What lives here | Owned by us? | Reset mechanism |
|---|---|---|---|
| <PostgreSQL> | <orders, users> | yes | <migrate:reset> |
| <Redis> | <sessions, cache> | yes | <flushdb> |
| <Search index> | <product catalog> | yes | <reindex command> |
## Environments
| Environment | Who can reach it | Purpose | Can agents run here? |
|---|---|---|---|
| local | | | |
| PR preview | | | |
| staging | | | |
| production | | | |
## Access and Credentials
| Credential | Needed for | Source | Can an agent hold it? |
|---|---|---|---|
| <VAR> | | <vault / sandbox / generated> | yes / no, and why |
Network barriers: <VPN, bastion, service mesh, mutual TLS>
## Architecture Summary
<One paragraph. Where does the data the features actually depend on live? Is
this app self-contained, a frontend over one API, one service among many, or a
thin client with no data of its own? State what that implies for Steps 3 and 4.>
## Open Questions
| Question | Who would know | Blocking? |
|---|---|---|
Definition of Done: Both tables are completed and verified alongside a client engineer, and you have documented where core data lives and how that impacts the remaining steps.
Step 2: Get-App-Running Skill
BUILD · Pillar 1: Run It
If an AI agent can't launch and interact with an application, it can't verify its own work. Teaching the agent how to run the app locally unlocks every other capability down the line.
This step is also a fantastic early win for the client: local environment setup is a common source of developer friction, so building a clean, reliable setup skill immediately helps human developers on the team too!
Watch Out for False Positives: A setup script that launches a process but fails to verify if the server is actually responding can lead an agent to assume success when the app actually crashed. Verification is the most critical part of this skill!
Discovery Questions
The Setup Sequence
What runtime environment versions are required, and how are they pinned?
What is the step-by-step dependency installation process? Are there private package registries requiring auth?
What steps only need to run once (e.g., generating SSL certs, initial database creation) vs. every time?
Are there mandatory startup order constraints? (e.g., database must be healthy before API launches)
What is the process for getting an old version of the repository back up to date with the current version, including the data?
Configuration & Credentials
Which environment variables are required? Is there an .env.example file, and is it up to date?
Where do developers safely get secrets for local development?
Which of these credentials can be safely made available to an agent?
Startup & Health Verification
What is the precise start command? Are multiple processes launched in parallel?
How long does startup usually take? How can the agent tell "still booting" apart from "crashed"?
How do we prove the app is truly ready? What URL, endpoint response, or log output confirms success?
Troubleshooting Common Issues
What are the known setup hiccups that new developers encounter?
What typically breaks when switching git branches (e.g., outdated dependencies, pending migrations)?
What is the team's standard "reset and try again" procedure when things get stuck?
Deliverables
A robust get-app-running skill. This one is different at every client, so the template is a scaffold rather than something you can adapt from elsewhere.
---
name: get-app-running
description: Use this skill to start, stop, or restart the application, when setting up from a fresh clone, or when the app will not start. Also use before any task that requires exercising the running app. Covers dependency installation, environment configuration, required services, and health verification.
---
# Get App Running
## Purpose
Guide the workspace from a fresh git clone to a verified, fully functioning
local application state without requiring manual human intervention.
## When to Use This Skill
- Setting up work in a fresh clone or new environment
- The application is not running and needs to be started
- The application is in an unstable state and requires a clean restart
- Before performing any task that requires running or testing the app
## Architecture Overview
<Two or three sentences explaining the core components and how they interact.>
| Component | Port | Depends on |
|---|---|---|
| <web> | <3000> | <api> |
| <api> | <4000> | <database> |
## Prerequisites
- <Runtime and version, and how it is pinned>
- <Package manager>
- <Container runtime, if applicable>
## First-Time Setup
Run these once. Skip to Starting the App if the environment is already prepared.
1. Install dependencies:
`<install command>`
2. Create the environment file:
`cp .env.example .env`
| Variable | How to obtain |
|---|---|
| <VAR_NAME> | <vault path, sandbox account, or generated locally> |
STOP if you cannot obtain a required value. Report exactly which variable
is missing and where it comes from. Do not invent a placeholder.
3. Start backing services:
`<e.g. docker compose up -d>`
4. Initialize the database:
`<migration command>`
## Updating an out of date version of the codebase
...
## Starting the App
`<start command>`
Startup takes roughly <N> seconds. Normal output looks like <description>.
"Still starting" looks like <X>. "Failed" looks like <Y>.
## Verifying It Worked
Do not report success until every check passes:
- [ ] <URL> returns HTTP 200
- [ ] <health endpoint> reports all services healthy
- [ ] The log contains <expected readiness line>
- [ ] No errors in <log location>
A partial start is possible: <e.g. the web tier can come up while the API is
dead>. Check every component, not just the first one.
If any check fails, see Common Failures before reporting a problem.
## Stopping and Restarting
Graceful stop: `<stop command>`
Full clean reset: `<teardown and restart sequence>`
## Common Failures
| Symptom | Cause | Fix |
|---|---|---|
| <port already in use> | <stale process> | <command> |
| <module not found> | <stale deps after branch switch> | <command> |
| <connection refused> | <service not started> | <command> |
| <migration pending> | <branch switch> | <command> |
## Known Limitations
<What this does not cover: production deploys, cloud environments if a separate
skill handles those, anything requiring credentials the agent cannot obtain.>
---
name: run-in-cloud
description: Use this skill to start the application in a Codespace, devcontainer, or hosted sandbox rather than on a local machine. Use when the local machine cannot run the full stack, or when the user asks to work in the cloud environment.
---
# Run in Cloud Environment
## Purpose
Bring the application up in <hosted environment> and verify it, for cases where
a local run is not possible or not wanted.
## When to Use This Instead of get-app-running
- <A required service is only reachable from inside the network>
- <The local machine cannot meet resource requirements>
- <The client requires agent work to happen in a controlled environment>
## What Differs from Local
| Concern | Local | Cloud |
|---|---|---|
| Secrets source | <.env file> | <injected by platform> |
| Ports | <localhost> | <forwarded URLs> |
| Data | <local database> | <shared or ephemeral> |
## Steps
1. <Launch or attach to the environment>
2. <Confirm secrets are present>
3. <Start services>
4. <Resolve the forwarded URL and verify health against it>
## Verifying It Worked
- [ ] <forwarded URL> returns HTTP 200
- [ ] <platform-specific health check>
## Known Limitations
<Cost, session timeouts, what does not persist between sessions.>
Definition of Done: An agent can take a completely fresh repository clone to a running, verified application state with zero human assistance.
Testing Tip: Always test this skill on a clean virtual machine, container, or temporary environment, never on your personal dev machine, which already has tools and credentials cached! Try prompting the agent with "Get this app running and confirm it works." If you have to step in, add whatever detail was missing directly into the skill document!
Step 3: Service Mocking & the Data Boundary
BUILD IF MISSING · Pillar 2: Control Its Data
Now that the application runs, we need to ensure the agent can work effectively even when third-party services are unavailable or unpredictable.
Depending on your architecture, "controlling data" might mean populating a local database, or it might mean setting up mock responses for external APIs. Step 1's topology mapping will guide your approach here.
A Note on Mock Drift: Over time, mock responses can drift from actual production API behavior. It's a great practice to discuss mock maintenance ownership with the engineering team early so everyone is aligned on who keeps specs up to date after handover.
Discovery Questions
For each external connection identified in Step 1, does the agent truly need access to complete its scoped work? (If not, keeping it out of scope simplifies setup!)
Does the external provider offer a dedicated sandbox or mock mode?
Do any local API mocks, test fixtures, or contract tests already exist in the codebase?
Where is the official API contract defined? (e.g., OpenAPI spec, GraphQL schema, Protobuf definitions)
What edge cases or error conditions need to be mocked beyond standard success calls? (e.g., rate limits, invalid auth, empty payloads)
Architecture Choice: Should mocks be hosted within the consumer application repository (fast & simple) or centrally in the service repository (more aligned with backend standards)?
Are there network security policies (like mutual TLS or private VPNs) that impact local API testing?
Deliverables
A lightweight mock setup for the integrations that block local work, plus a skill that lets the agent drive it.
---
name: mock-services
description: Use this skill to run the application against mocked external services, switch a service between live and mocked, or load a specific mock response scenario. Use when an external service is unavailable, when a test needs a specific external response such as an error or timeout, or when the user asks to "mock <service>" or "use the sandbox".
---
# Mock External Services
## Purpose
Let the agent run and exercise the application without depending on live
external services, and control exactly what those services return.
## Services Covered
| Service | Default mode | How to toggle | Contract source |
|---|---|---|---|
| <Payments> | mocked | <env var or config flag> | <OpenAPI spec path> |
| <User service> | live | <env var> | <proto path> |
| <Email> | mocked | <env var> | <provider docs URL> |
## Switching Modes
Run with everything mocked: `<command>`
Run against the provider sandbox: `<command>`
Run fully live: `<command, or state that this is not available locally>`
## Available Scenarios
| Scenario | Service | What it simulates |
|---|---|---|
| <payments-success> | <Payments> | happy path, card accepted |
| <payments-declined> | <Payments> | 402, insufficient funds |
| <payments-timeout> | <Payments> | no response within <N>s |
| <users-empty> | <User service> | valid response, zero results |
| <auth-expired> | <any> | 401, expired token |
Load a scenario: `<command> <scenario-name>`
List active scenarios: `<command>`
## What Is Real and What Is Stubbed
<State this explicitly for each mode.> When reporting a failure, always say
whether the service involved was mocked. A mock artifact and a real bug look
identical in a stack trace, and attributing one to the other wastes hours.
## Adding a New Scenario
1. Find the real contract at <location>. If there is no written contract,
capture a real response first and record where it came from.
2. Add the fixture to <path>, following the shape of the existing ones.
3. Register it in <manifest or index file>.
4. Verify with `<command>`.
## Known Limitations
<Which behaviors the mock does not reproduce: rate limiting, pagination,
webhook callbacks, eventual consistency.>
Mocks drift. Last verified against the live contract on <YYYY-MM-DD>.
Owner after handover: <name>.
---
name: verify-mock-contract
description: Use this skill to check whether local mocks still match the real service contract. Use on a schedule, before a release, or when a test passes locally but the same code fails against a live environment.
---
# Verify Mock Contract
## Purpose
Catch mock drift deliberately rather than discovering it as a mystery bug.
## What to Compare
| Mock | Compare against | Method |
|---|---|---|
| <payments fixtures> | <OpenAPI spec at URL> | <schema diff command> |
| <user service fixtures> | <.proto in repo X> | <regenerate and diff> |
## Steps
1. Fetch the current contract from <source>.
2. Validate each fixture in <path> against it.
3. Report any field that was added, removed, renamed, or changed type.
4. For anything that changed, say whether existing scenarios are still valid.
## Reporting
Produce a short table of drift found, and for each row state whether it is
cosmetic or would change application behavior. Do not silently update
fixtures: drift is information the team needs to see.
## Known Limitations
<Schemas cannot express behavior. Field-level checks will not catch changed
semantics, new required headers, or altered error codes.>
Definition of Done: The agent can launch the application with external dependencies mocked, simulate at least one specific error scenario, and the team has agreed on long-term mock ownership.
Step 4: Data Seed & Reset Skill
BUILD IF MISSING · Pillar 2: Control Its Data
To verify application features thoroughly, an agent needs to control database state. Testing an "expired subscription" feature requires putting the database into an expired subscription state on demand, and then cleanly resetting it afterward.
Without clear seeding skills, agents tend to test against whatever leftover data exists in the database, leading to inconsistent test results.
Discovery Questions
What data stores are in use? (e.g., primary DB, Redis cache, search indexes)
Does a seed or fixture script already exist, and does it currently work?
How is a clean reset performed today? (e.g., dropping the schema, rolling back transactions, running a reset script)
How long does a full data reset take? (Aim for fast resets, scripts taking more than a couple of minutes slow down agent feedback loops.)
What specific data scenarios does the development team test frequently? (e.g., new-user-no-orders, subscribed-user-past-due)
Are there core baseline records that must exist for the app to function? (e.g., default user roles, feature flags, configuration tables)
If someone is using an out of date version of the repo, how can they update the data once they’ve checked out the latest version?
Deliverables
A seed-and-reset skill. Named scenarios are what make this useful in practice: a generic seeder gets ignored, while expired-subscription gets used every day.
---
name: seed-and-reset
description: Use this skill to reset application data to a clean baseline, load a named test scenario, or check which data state the app is currently in. Use before testing any feature that depends on specific data, after a test run leaves data dirty, or when test results look inconsistent between runs.
---
# Seed and Reset Data
## Purpose
Put the application into a known, named data state on demand, and get back to
a clean baseline afterward.
## Data Stores
All of these have to be handled together. Resetting one and not the others is
the most common cause of confusing state.
| Store | Reset command | Notes |
|---|---|---|
| <PostgreSQL> | <command> | primary source of truth |
| <Redis> | <command> | must be flushed with the DB or it serves stale reads |
| <Search index> | <command> | needs a reindex after any DB reset |
| <Blob storage> | <command> | <local emulator or real bucket> |
## Reset to Clean
`<reset command>`
Takes roughly <N> seconds. This drops <what> and restores the baseline
records below.
## Baseline Records
These must exist or the app will not boot: <default roles, feature flags,
admin user, reference tables>. They are restored automatically by the reset
command and should never be deleted by a scenario.
## Named Scenarios
| Scenario | State it produces |
|---|---|
| <new-user-no-orders> | <one user, empty order history> |
| <subscribed-user-past-due> | <active subscription, failed last payment> |
| <order-mid-fulfilment> | <order placed, partially shipped> |
| <large-dataset> | <N records, for pagination and performance work> |
Load a scenario: `<seed command> <scenario-name>`
List scenarios: `<command>`
## Checking Current State
`<command that reports the active scenario or a state fingerprint>`
Always check state before drawing a conclusion from a test. A feature that
"works" against unknown data has not been tested.
## Adding a Scenario
1. Start from a clean reset so the scenario is reproducible.
2. Add the fixture or factory to <path>, following the existing pattern.
3. Register it in <manifest> with a one-line description of the state.
4. Verify: reset, load the scenario, and confirm the state is what you claimed.
## Known Limitations
<What cannot be seeded locally: data behind external services (see the mocking
skill), anything requiring a real third-party account, production-scale volume.>
---
name: explore-schema
description: Use this skill to inspect the database schema, find which tables hold a given concept, or trace relationships between records. Use when writing a seed scenario, when a query returns unexpected results, or when the user asks where some piece of data lives.
---
# Explore Schema
## Purpose
Answer "where does this data live and how is it related" without guessing.
## Connecting
`<read-only connection command>`
Use the read-only credential. Never run mutations through this skill; use
seed-and-reset for that.
## Schema Map
| Domain | Primary tables | Notes |
|---|---|---|
| <Users and auth> | | |
| <Orders> | | |
| <Billing> | | <partly external, see topology.md> |
## Useful Queries
List tables and row counts: `<query>`
Describe a table with constraints: `<query>`
Find foreign keys pointing at a table: `<query>`
## Gotchas
<Soft deletes, denormalized copies, tables that look authoritative but are
caches, columns that are unused but not dropped.>
Definition of Done: The agent can successfully execute commands like "Put the app in the expired-subscription state" and then "Reset to clean baseline" completely unassisted.
Step 5: Version Control & Delivery Workflow
BUILD · Pillar 5: Ship It
An AI agent's work should flow through the same git conventions, branch naming patterns, and code review processes as human team members.
Discovery Questions
What is the team's branch naming convention? (e.g., feature/JIRA-123-short-description)
What commit message format is expected? (e.g., Conventional Commits, ticket prefixes)
What are the requirements for a pull request? (e.g., template structure, linked ticket references, mandatory tags)
What checks run in CI when a PR is created, and how long do they take?
Does the repository generate PR preview environments?
What git operations are strictly forbidden for agents? (e.g., force pushing, committing directly to main, editing lockfiles manually)
Deliverables
Usually two or three small skills rather than one large one, since branching, committing, and opening a PR happen at different moments.
---
name: branch-and-commit
description: Use this skill to create a correctly named branch or write a commit message that follows team conventions. Use proactively at the start of any new piece of work if currently on the default branch, and whenever changes are ready to commit.
---
# Branch and Commit Conventions
## Branch Format
`<type>/<TICKET-KEY>-<brief-description>`
With no ticket: `<type>/no-ticket-<brief-description>`
| Type | When to use |
|---|---|
| <feat> | New feature |
| <fix> | Bug fix |
| <refactor> | Neither a fix nor a feature |
| <chore> | Tooling, dependencies, build |
| <docs> | Documentation only |
| <test> | Tests only |
Rules:
1. Lowercase and hyphens only in the description, 2 to 5 words.
2. Ticket key uppercase, immediately followed by a hyphen.
3. When work spans several tickets, use the parent ticket.
4. <Any client-specific rule, e.g. a required team prefix.>
Examples:
- <feat/PROJ-12-add-oauth-login>
- <fix/PROJ-88-null-payment-response>
## Commit Format
`<type>(<optional scope>): <description>`
Breaking changes: add `!` after the type or scope, or a
`BREAKING CHANGE: <description>` footer.
Rules:
1. Imperative mood, lowercase, no trailing period.
2. Subject line under <72> characters including type and scope.
3. Scope is the most affected module. Omit it when changes span many areas.
4. <Whether history is squashed on merge, and what that means for message care.>
## Steps
1. Run `git status` and `git diff` (or `git diff --staged`) to see what changed.
2. Infer the type from the nature of the change.
3. Draft the branch name or commit message and show it to the user before
running anything.
4. On confirmation, run the command.
## Never Do These
- <Commit directly to main>
- <Force push to a shared branch>
- <Edit lockfiles by hand>
- <Commit generated files under <path>>
These are always-on rules, so also record them in the instructions file
(see Step 10) rather than relying on this skill being loaded.
---
name: open-pr
description: Use this skill to open a pull request following team guidelines. Runs pre-flight checks, runs the required local checks, fills in the PR template, creates the PR, and reports CI status. Use when the user asks to "open a PR", "create a PR", or "submit this for review".
---
# Open a Pull Request
## Purpose
Take committed work to an open, correctly formatted PR with CI running.
## Step 1: Pre-flight Checks
Run these and inspect each result:
```
git status --porcelain
git branch --show-current
git rev-parse --abbrev-ref origin/HEAD
git log @{u}..HEAD --oneline
```
Abort with a clear message if any of these hold:
| Condition | Message |
|---|---|
| Working tree is dirty | "You have uncommitted changes. Commit or stash first." |
| On the default branch | "Switch to a feature branch before opening a PR." |
| A PR already exists for this branch | "PR already open at <url>. Update it instead?" |
Warn but do not block if the branch name does not match the convention.
## Step 2: Run Required Checks
These must pass before opening the PR:
| Check | Command | Typical duration |
|---|---|---|
| <Tests> | <command> | <N> |
| <Lint> | <command> | <N> |
| <Types> | <command> | <N> |
| <Build> | <command> | <N> |
If any fail, stop and fix them. Do not open a PR with known failures unless
the user explicitly asks for a draft.
## Step 3: Self-Review the Diff
Read `git diff <base>...HEAD` and check for debug statements, commented-out
code, secrets, unrelated changes, and anything the team's review checklist
flags. Fix what you find before continuing.
## Step 4: Fill In the PR Template
Required sections at this client:
| Section | Content |
|---|---|
| <Summary> | <what changed and why, 2-3 sentences> |
| <Ticket> | <linked ticket, required / optional> |
| <Testing> | <how it was verified, including scenario used> |
| <Screenshots> | <required for UI changes> |
Base branch: <default>. Always confirm the base with the user.
## Step 5: Create It
`<gh pr create command, or the client's equivalent>`
## Step 6: Report Back
Give the user the PR URL, the CI status, and the preview environment URL if
one is generated. If CI is still running, say so rather than implying it passed.
## Known Limitations
<Reviewer assignment rules, paths that need extra approval, anything the agent
must hand to a human.>
Definition of Done: The agent takes local changes, creates an appropriately named branch, commits with the team's standard message format, opens a PR, and checks whether initial CI checks passed.
🛑 Foundation Checkpoint
Pause here for a quick sanity check before moving forward!
In a fresh session, test a complete end-to-end flow with a single prompt. Ask the agent to launch the app, seed a specific test data scenario, make a minor and safe code change, commit and push to a new branch, then open a pull request.
If this works smoothly from start to finish, your core foundation (Steps 1 to 5) is rock solid! If something breaks, fixing it now provides massive value before moving into design and requirements.
Step 6: Requirements Sourcing
BUILD · Pillar 3: Know What to Build
Rather than asking developers to manually copy and paste ticket details into a chat box, we can enable the agent to read ticket requirements and design files directly from tools like Jira, Notion, or Figma.
Even better: the agent can compare requested changes against existing code structures early on, helping spot potential conflicts or missing API parameters before writing a single line of implementation code!
Discovery Questions
Where are feature requirements and tickets managed? (e.g., Jira, Linear, GitHub Issues)
Where do UI/UX design assets live? (e.g., Figma)
Can API keys or Model Context Protocol (MCP) integrations be provided to access these services safely?
What information makes up a well-written ticket in this organization?
When requirements seem ambiguous, who does a developer reach out to for clarification?
Deliverables
MCP or API connections, plus a skill that turns a ticket reference into a grounded understanding of the work.
Worth knowing: connecting an MCP server is rarely the hard part. Getting good results is mostly about the skill you wrap around it, which shapes how the agent uses that connection in this particular codebase.
---
name: get-requirements
description: Use this skill to pull a ticket and its linked designs, then cross-check them against the codebase before any implementation starts. Use whenever the user gives a ticket ID or link, or asks what needs to be built. Do not start writing code from a ticket without running this first.
---
# Get Requirements
## Purpose
Turn a ticket reference into a grounded, verified understanding of the work,
including any conflicts with what the code actually does today.
## Sources
| Source | Access method | What to pull |
|---|---|---|
| <Jira> | <MCP server or API> | description, acceptance criteria, comments, links |
| <Figma> | <MCP server> | linked frames, component names, spacing and states |
| <Confluence or docs> | <MCP server> | linked specs |
## Steps
1. Fetch the ticket. Read the description, the acceptance criteria, and the
comment thread. Comments frequently contain the real requirement.
2. Follow every link on the ticket. Designs, related tickets, prior PRs.
3. Locate the code the change touches. Name the specific files.
4. Cross-check the request against reality and list any conflicts:
- Does every field the ticket references exist in the API and the model?
- Does the design use components that exist, or invent new ones?
- Does the request contradict existing behavior somewhere else?
- Is there an existing implementation that partly covers this already?
5. Note what a good ticket at this client contains, and what is missing here.
6. Produce the summary below. Do not begin implementing.
## Output Format
```
## Ticket
<key and title, link>
## What Is Being Asked
<plain restatement, 2-4 sentences>
## Acceptance Criteria
<as written, or reconstructed if absent>
## Code This Touches
<file paths, with one line each on what changes>
## Conflicts and Gaps
<numbered. Each one: what the ticket assumes, what the code does, and the
question this raises. Empty is a valid answer, but only after checking.>
## Open Questions for <role who resolves ambiguity>
<numbered>
```
## When to Stop and Ask
Stop and surface questions rather than guessing when the acceptance criteria
are missing, when a conflict changes the shape of the work, or when the design
and the ticket disagree. At this client, ambiguity goes to <role or name>.
## Known Limitations
<Tickets the agent cannot see, projects requiring separate permissions,
designs that live outside the connected tool.>
Definition of Done: Given a ticket ID, the agent independently retrieves the issue details and linked designs, while highlighting any conflicts with existing code.
Step 7: Planning, Spec & Prototyping
BUILD · Pillar 3: Know What to Build
Encouraging the agent to generate an explicit plan or lightweight specification before coding saves tremendous time. Reviewing a 1-page architecture plan takes a human developer two minutes, whereas reviewing 500 lines of unexpected code changes takes much longer!
For frontend tasks, creating quick UI prototypes using existing design system components allows teams to validate visual ideas rapidly before integrating backend logic. Because the prototype is built from components that already exist, it doubles as a check on whether a proposed design is actually buildable from what's there.
Discovery Questions
What is the team's existing design or spec process before starting major work?
How detailed should a plan be for small fixes vs. major feature additions?
Who reviews and approves specs before engineering begins?
For visual features, would the design/product team prefer reviewing an interactive prototype over written notes?
Deliverables
A planning skill, and for visual work a prototyping skill alongside it.
---
name: create-spec
description: Use this skill to produce a reviewable implementation plan before writing code. Use for any change beyond a trivial fix, after requirements have been gathered, and whenever the user asks for a plan, spec, or approach. Stop for sign-off before implementing.
---
# Create Spec
## Purpose
Produce a plan a human can review in two minutes, so a wrong approach gets
caught before it becomes 500 lines of code.
## When a Spec Is Required
| Change size | Spec needed? |
|---|---|
| <Typo, copy change, config value> | no, just do it |
| <Single-file bug fix> | <short paragraph in the PR> |
| <New component or endpoint> | yes, full spec |
| <Schema change or new dependency> | yes, plus <role> sign-off |
## Steps
1. Confirm requirements are gathered and conflicts resolved.
2. Find the closest existing implementation in the codebase and read it. The
plan should follow that pattern unless there is a stated reason not to.
3. Write the spec using the format below.
4. Present it and stop. Do not write implementation code until the user or
<reviewer role> approves.
## Spec Format
```
## Goal
<One or two sentences. What will be true when this is done.>
## Approach
<How, in prose. Name the pattern being followed and the file it comes from.>
## Changes
| File | Change |
|---|---|
| <path> | <what and why> |
## Data and Contract Changes
<Schema migrations, API shape changes, new environment variables. Say "none"
explicitly if there are none.>
## Testing
<What tests get written, which data scenario they need, what proves it works.>
## Risks and Alternatives
<What could go wrong, and any approach considered and rejected, with why.>
## Out of Scope
<What this deliberately does not do.>
```
## Storage
Specs live at <path or tool>, named <convention>.
## Known Limitations
<When a spike is more appropriate than a spec, and how to say so.>
---
name: build-prototype
description: Use this skill to build a throwaway visual prototype from the components that already exist in this codebase, for sign-off before real implementation. Use for any visual or UX change where a picture would settle a question faster than prose.
---
# Build Prototype
## Purpose
Show what a change will look like, using only components that already exist,
so the prototype doubles as proof the design is buildable from what is there.
## Component Inventory
| Where components live | How to list them |
|---|---|
| <path> | <command or index file> |
Design system source of truth: <Storybook URL, Figma library, or path>
## Steps
1. Inventory the existing components relevant to the request.
2. Assemble the prototype as <throwaway HTML/CSS, or a scratch route>. Do not
write production framework code at this stage.
3. Where the design calls for something that does not exist, do not invent it
silently. Build the closest existing component and list the gap explicitly.
4. Output the prototype plus a "what does not exist yet" list.
## Rules
- Output is disposable. It goes in <scratch location> and is never merged.
- Real data is not required, but note where mock data was used.
- The gap list is the most valuable output. A design needing three new
components is a very different estimate from one needing none.
## Known Limitations
<Interactions, animation, responsive behavior, accessibility, and anything else
the prototype does not attempt to prove.>
Definition of Done: The agent reliably produces a clear implementation plan for human review and waits for sign-off before modifying core codebase logic.
Step 8: Implementation
BUILD · Pillar 4: Build It & Prove It Works
When writing implementation code, the agent should follow local architectural conventions so its contributions seamlessly blend with the existing codebase.
Much of this success comes down to providing clear reference examples within the codebase that the agent can model its work after.
Discovery Questions
What architectural patterns should new feature modules follow? (e.g., controller-service-repository patterns, modular component folders)
Which specific files in the repository serve as ideal "gold standard" examples for new work?
Are there legacy patterns or deprecated utility functions that the agent should explicitly avoid?
What libraries or packages are approved for common tasks (and are any prohibited)?
What files usually need to change together when adding a feature? (e.g., database schema + type definitions + API routes + unit tests)
Deliverables
An implementation skill, plus a patterns reference file it can point at. The "what changes together" answer is usually the single most valuable thing you write down at this step.
---
name: implement-feature
description: Use this skill when writing or modifying application code, so the result follows this codebase's established patterns. Use after a spec is approved. Covers where code goes, which patterns to copy, what to avoid, and what has to change together.
---
# Implement Feature
## Purpose
Write code that looks like it belongs in this codebase, rather than a correct
solution in a foreign style.
## Reference Implementations
Copy the pattern from these files. When in doubt, imitate rather than invent.
| To build this | Copy the pattern from |
|---|---|
| <A new API endpoint> | <path> |
| <A new UI component> | <path> |
| <A new background job> | <path> |
| <A database migration> | <path> |
## Where Code Goes
```
<directory tree with a one-line note per folder>
```
## What Changes Together
The most common source of half-finished work. Adding <a field to a model>
means touching all of these:
| Change | File or location |
|---|---|
| <Migration> | <path> |
| <Model or type definition> | <path> |
| <API serializer or route> | <path> |
| <Client-side type> | <path> |
| <Tests> | <path> |
| <Seed scenario, if the field is required> | <path> |
## Approved Libraries
| Job | Use | Do not use |
|---|---|---|
| <Dates> | <library> | <library> |
| <HTTP calls> | <library> | <library> |
| <Forms> | <library> | <library> |
| <State> | <library> | <library> |
Adding a new dependency requires <approval process>.
## Deprecated: Do Not Copy These
| Pattern or file | Still present because | Use instead |
|---|---|---|
| <path or pattern> | <not yet migrated> | <replacement> |
This table matters as much as the reference list. An agent reading the
codebase cold cannot tell current patterns from abandoned ones.
## Steps
1. Re-read the approved spec.
2. Open the reference implementation for this kind of change and follow it.
3. Work through the "what changes together" table and confirm each row is
either done or genuinely not applicable.
4. Run the verification skill before reporting anything as complete.
<This is also a good place to outline any specific workflow for implementation, ex "Test Driven Development", or "Using Subagents to do the implementation"
## Known Limitations
<Areas of the codebase where the pattern is unclear or contested, and who to
ask about them.>
Definition of Done: Code written by the agent passes team code reviews smoothly, matching the style, structure, and patterns of surrounding files.
Step 9: Verification & Self-Testing
BUILD · Pillar 4: Build It & Prove It Works
A great AI agent doesn't just write code, it verifies its own work by running test suites, analyzing failure logs, and applying fixes before turning things over for human review.
Discovery Questions
What test suites exist in the repository (unit, integration, end-to-end), and how are they run?
How long do test suites take to execute? Are any tests known to be flaky?
What automated checks are mandatory before submitting a PR? (e.g., linting, type checks, unit tests)
Does the repository use browser automation tools like Playwright or Cypress that an agent can execute?
How does the agent access detailed test logs or failure screenshots to debug issues?
Deliverables
A verification skill that covers which checks to run when, how to read the output, and the fix-and-rerun loop.
---
name: verify-changes
description: Use this skill to verify a change actually works before reporting it as complete or opening a PR. Covers which test suites to run, how to interpret failures, which tests are unreliable, and the fix-and-rerun loop. Always use this before claiming work is done.
---
# Verify Changes
## Purpose
Prove the change works, rather than asserting that it should.
## Check Ladder
Run in this order. Cheap and fast first, so failures surface early.
| Check | Command | Duration | Run when |
|---|---|---|---|
| <Types> | <command> | <N>s | every change |
| <Lint> | <command> | <N>s | every change |
| <Unit tests> | <command> | <N>s | every change |
| <Unit tests, single file> | <command> <path> | <N>s | while iterating |
| <Integration tests> | <command> | <N>m | touching API or data layer |
| <End-to-end / browser> | <command> | <N>m | touching UI or a user flow |
| <Build> | <command> | <N>m | before opening a PR |
## Prerequisites
Integration and end-to-end tests need <the app running / a specific data
scenario>. Use the get-app-running and seed-and-reset skills first, and record
which scenario was loaded.
## Reading Failures
| Where to look | What is there |
|---|---|
| <Test output path> | <failure details> |
| <Screenshot or trace dir> | <browser test artifacts> |
| <App log location> | <server-side errors during the test> |
## Known Flaky Tests
| Test | Symptom | What to do |
|---|---|---|
| <path or name> | <fails intermittently on timing> | <rerun once; if it fails twice it is real> |
Do not conclude a change is broken from a single failure in this table, and do
not conclude it works because a flaky test happened to pass.
## The Loop
1. Run the appropriate checks from the ladder.
2. On failure, read the actual error before changing anything.
3. Fix the cause, not the symptom. Do not delete or skip a test to get green.
4. Rerun the failing check, then rerun the full ladder.
5. Report what you ran, what passed, and anything you could not verify.
## Writing New Tests
| Change type | Test expected |
|---|---|
| <Bug fix> | <a test that fails before the fix> |
| <New endpoint> | <integration test, happy path plus one error> |
| <New component> | <unit test, plus e2e if it is in a critical flow> |
Follow the pattern in <reference test file>.
## Never Report Success If
- A check was skipped and you did not say so
- A test was modified to make it pass
- The app was not actually running for a test that needs it
Definition of Done: When given a task that intentionally breaks a unit test, the agent detects the test failure, diagnoses the root cause, fixes the issue, and confirms all tests pass.
Step 10: Coding Standards & Code Review
BUILD · Pillar 4: Build It & Prove It Works
This step brings together two core artifacts:
Instruction File (CLAUDE.md / AGENTS.md): High-level rules loaded in every session (architecture style, preferred libraries, prohibited practices).
Code Review Skill: An on-demand review step where the agent audits its own pull request against team guidelines before notifying human reviewers.
Rule of Thumb: Use the global instruction file for always-on guidelines that shape code as it's written. Use the code review skill for checklist verifications applied to completed work!
Discovery Questions
Does the team have written style guides or coding standards?
Is there an existing instructions file, and has it drifted out of date?
What feedback repeatedly comes up during human code reviews? (That list makes a fantastic review checklist!)
What issues result in an automatic PR rejection?
Which checks are already handled automatically by linters or formatters?
Deliverables
Two artifacts, and they are genuinely different things. The instructions file is loaded on every prompt and should stay short. The review skill is loaded on demand and can be long.
# <Project Name>
<One paragraph: what this application is and who uses it.>
## Architecture
<Three or four sentences on the shape of the system. Point at the detail
rather than restating it: see docs/ai-enablement/topology.md.>
## Non-Negotiable Rules
<Keep this list short and absolute. Anything conditional belongs in a skill,
not here.>
- Never commit directly to <main>.
- Never force push to a shared branch.
- Never edit <lockfile> by hand.
- Never commit secrets, or invent a value for a missing one. Stop and ask.
- Never modify or skip a test to make a suite pass.
- <Client-specific absolute rule>
## Conventions
| Area | Convention |
|---|---|
| Branch names | <format> |
| Commit messages | <format> |
| File naming | <convention> |
| <Language-specific style> | <handled by <formatter>, do not hand-format> |
## Approved Libraries
| Job | Use | Not |
|---|---|---|
| <Dates> | | |
| <HTTP> | | |
## Before You Report Work Complete
1. The app runs and you verified it, not assumed it.
2. The required checks pass. See the verify-changes skill.
3. Everything in the "what changes together" table is done.
## Available Skills
| Skill | Use it when |
|---|---|
| get-app-running | starting, stopping, or fixing the local app |
| seed-and-reset | you need a specific data state |
| mock-services | an external service is unavailable or needs a specific response |
| get-requirements | you have a ticket and need to know what to build |
| create-spec | any non-trivial change, before writing code |
| implement-feature | writing or modifying application code |
| verify-changes | before reporting anything as done |
| open-pr | the work is ready for review |
Keep this file under <a page or two>. It is loaded on every prompt, so
anything conditional or lengthy belongs in a skill instead.
---
name: review-changes
description: Use this skill to review a diff against this team's guidelines before a human reviewer sees it. Use before opening a PR, after finishing implementation, or when the user asks for a review or self-review.
---
# Review Changes
## Purpose
Catch the things this team's reviewers always catch, before they have to.
## What to Review
`git diff <base>...HEAD`
Review the diff, not the whole codebase. Pre-existing problems outside the
diff get noted separately, never fixed silently in this change.
## Automatic Rejections
Check these first. Any hit here is a stop.
| Check | Why |
|---|---|
| <Secrets or credentials in the diff> | |
| <Commented-out code left behind> | |
| <Debug statements or console logging> | |
| <Test modified or skipped to pass> | |
| <Changes unrelated to the stated purpose> | |
| <Migration without a rollback path> | |
## Team Review Checklist
Built from what actually comes up in this team's PR comments.
| Area | Check |
|---|---|
| <Error handling> | <are failures handled the way <path> does it> |
| <Naming> | <matches the convention in the instructions file> |
| <Types> | <no escape hatches added without a comment explaining why> |
| <Tests> | <new behavior has a test that would fail without the change> |
| <Accessibility> | <for UI: labels, focus order, keyboard reachability> |
| <Performance> | <no queries inside loops, no unbounded fetches> |
| <Security> | <inputs validated, authorization checked at the boundary> |
## Already Automated, Do Not Comment On
<Formatting, import order, and anything else the linter or formatter owns.
Flagging these adds noise and trains the team to ignore the review.>
## Output Format
```
## Blocking
<numbered, each with file:line and what to change. Empty is fine.>
## Worth Considering
<numbered, non-blocking>
## Outside This Diff
<pre-existing issues noticed but deliberately not fixed here>
```
Be specific. "Consider improving error handling" is not actionable;
"<path>:42 swallows the error, follow the pattern in <path>:88" is.
Definition of Done: The agent's automated pre-review catches common code feedback items before human developers review the PR.
Step 11: Skill Maintenance
ADVISE
As software evolves, build commands change, dependencies update, and workflows shift. Establishing a clear maintenance strategy ensures the agent skills we build remain accurate and valuable over time.
Focusing on maintainability also helps avoid "knowledge silos," ensuring the entire team feels comfortable updating agent instructions as the codebase develops.
Discovery Questions
Who on the client team will own the upkeep of these AI skills after handover?
Which workflows or commands are most likely to change in the coming months?
Can automated CI checks verify that key setup skills (like get-app-running) continue to execute successfully?
How can team members suggest updates or report outdated agent skills?
Deliverables
A short maintenance agreement, plus at least one automated check so drift fails loudly instead of being discovered by the next agent.
# AI Skill Maintenance
Owner: <name>, <role>
Last reviewed: <YYYY-MM-DD>
## What Exists
| Skill | Purpose | Most likely to break when | Risk |
|---|---|---|---|
| get-app-running | local setup and health | <deps or services change> | high |
| seed-and-reset | data state control | <schema migrations> | high |
| mock-services | external service stubs | <the real API changes> | high |
| open-pr | delivery workflow | <CI or template changes> | medium |
| implement-feature | codebase patterns | <a pattern is deprecated> | medium |
| review-changes | review checklist | <standards evolve> | low |
## Automated Checks
| Check | What it runs | Frequency | On failure |
|---|---|---|---|
| <Setup smoke test> | <the get-app-running verification steps in CI> | <nightly> | <who is alerted> |
| <Mock contract check> | <verify-mock-contract> | <weekly> | <who is alerted> |
The cheapest high-value check is running the get-app-running verification
steps on a schedule against a clean container. A broken setup path is the
failure that silently invalidates everything else.
## Human Review Cadence
<Quarterly, or tied to a release.> At each review:
1. Run each skill once and confirm it still does what it claims.
2. Update the "last verified" date in each skill.
3. Delete skills nobody used. A stale skill is worse than no skill, because
the agent follows it confidently.
## How to Propose a Change
<Skills are code. They live in the repo, change by PR, and get reviewed the
same way. Name the reviewers.>
## Bus Factor
<Who else can maintain these besides the owner. If the answer is nobody,
that is the finding, and it should be raised rather than left implied.>
Definition of Done: A designated team member owns skill maintenance, and an automated check is in place to catch setup script drift.
Step 12: Measurement & Handover
ADVISE
Finally, we loop back to Step 0 to review our baseline metrics and highlight tangible improvements. Presenting a clear, honest summary helps leadership appreciate the real impact of the engagement!
Discovery Questions
How do current development metrics compare against our initial Step 0 baseline?
Which of the 5 AI Capability Pillars are now fully enabled?
What qualitative wins have developers noticed in their day-to-day work?
What remaining technical gaps or future opportunities should be shared with leadership?
Deliverables
A short report, written for the leadership audience you identified in Step 0.
# AI Enablement: <Client> — Engagement Report
Period: <start> to <end>
Prepared for: <the leadership audience named in Step 0>
## What We Set Out to Do
> <Their definition of success, quoted from Step 0.>
## Results Against Baseline
| Metric | Before | After | Measured how |
|---|---|---|---|
| <Local setup time for a new developer> | | | |
| <PR cycle time> | | | |
| <Lead time to production> | | | |
<Where a metric could not be re-measured the same way, say so. A number with
a caveat is credible; a number without one invites suspicion of all of them.>
## Capabilities Now in Place
| Pillar | Status | Evidence |
|---|---|---|
| Run it | <enabled / partial / not reached> | <what an agent can now do, unassisted> |
| Control its data | | |
| Know what to build | | |
| Build it and prove it works | | |
| Ship it | | |
## What Was Built
| Artifact | Location | Owner after handover |
|---|---|---|
| <skills> | <repo path> | <name> |
| <instructions file> | <repo path> | <name> |
| <topology document> | <repo path> | <name> |
| <mocks and fixtures> | <repo path> | <name> |
| <external connections> | <what is configured> | <name> |
## What Developers Noticed
<Two or three direct quotes. These carry more weight with leadership than the
metrics table, and they are free to collect.>
## Remaining Gaps
<Include these. A report with no gaps reads as marketing and gets discounted
along with everything else in it. For each gap: what it is, what it costs
them, and what closing it would take.>
## Recommended Next Steps
| Priority | Recommendation | Why now |
|---|---|---|
## Maintaining This
<Point at the maintenance agreement from Step 11. Name the owner, the
automated checks, and the review cadence.>
Definition of Done: The client receives a clear summary report suitable for leadership, and all documentation/skills are fully checked into the client repository.