CURRENT / Sources & referenceSource status

Current

Opening the reference…

Ship one AI feature · Current

Workflow · Documented baseline v4

Ship one AI feature

Build an AI triage feature through contracts, a mock adapter, bounded model calls, safe retries, evaluation, and operation.

6 detailed checkpoints. Work at your own pace. Live-provider setup and evaluation are separate.

The worked scenario

What you’ll build

Build a support-ticket triage assistant that suggests a category and explanation, retains the original ticket, and leaves the decision editable. The implementation guidance is framework-neutral; examples use TypeScript.

For: Developers who can run an existing server application and write a basic test.

Authored examples, reviewed 2026-10-16. Verify commands and integrations in your own environment.

Download the complete guide ↓

Before you start

An existing app and a passing baseline test command.
Permitted example tickets with no unnecessary personal data.
A transactional store for idempotency and cost reservations before live use.
Provider credentials and budget only when you reach the live-call step.

Skills used in this workflow

Make these choices first

Which model should I use?

Evaluate eligible models against your own clear and ambiguous tickets. Compare observed error modes, latency, and cost. This guide does not declare a universal winner.

Do I need an agent framework?

A single bounded request can use a small adapter. Add orchestration only when the task needs tools, multiple steps, or persisted recovery state.

When should I add RAG?

When the task requires private or changing knowledge that is absent from the request. First measure whether retrieval improves the specific failure cases; retain provenance and access boundaries.

Step 1 of 6

Write a contract you can test

A model cannot compensate for an undefined product decision. Keep triage suggestions separate from sending a reply or changing a ticket.

Start with

One real support ticket and a list of allowed categories.

What to do

Choose exactly one output: a suggested category plus a short rationale. Keep the original ticket unchanged.
Create five examples: a normal ticket, an ambiguous request, blank input, oversized input, and a ticket containing instructions to ignore your rules.
Set allowed categories and a 'needs-review' outcome. Record which fields are user-visible and which are diagnostic.

Worked example

A concrete acceptance case

Given: ‘Charged twice, and now I cannot log in.’
When: the user requests a triage suggestion
Then: suggest needs-review, retain the original ticket,
and let the user choose a category before any downstream action.

This is an authored test fixture. It expresses a product choice, not a benchmark result.

Give this task to your agent

Adapt the project details before using this instruction.

Agent instruction

Use frame-a-feature. Scope support-ticket triage with billing, account, bug, and needs-review categories. Produce Given/When/Then examples. Exclude automatic replies and account changes. Mark assumptions explicitly.

Your output

feature-brief.md and five input/expected-outcome fixtures.

Ready to move on when

An ambiguous ticket can return needs-review without inventing an answer.

The team disagrees about what a correct category is.

Resolve the ambiguous examples with the product owner before using them as evaluation labels.

View the stack

Definition of done

What a complete result includes

Blank and oversized input fail before a model call.
Unknown categories, malformed replies, and refusals never become successful suggestions.
Duplicate concurrent submissions cause one dispatch.
Uncertain calls retain cost reservations.
The user can recover without losing the original ticket.
Model quality is reported separately from mocked software tests.

Record evidence against each criterion in acceptance.md. A completed step is not proof that an integration works.

Reusable starting point

Take the working files with you.

Start with a brief, keep a verification record, and hand off the work with its assumptions. Preview each file before downloading. Skill files include their installation instructions below.

Download brief ↓

Files in this workflow

brief.mdA concrete task brief with decisions and acceptance cases.Download brief.md ↓

Preview file

brief.md

# Ship one AI feature: task brief

## Worked scenario
Build a support-ticket triage assistant that suggests a category and explanation, retains the original ticket, and leaves the decision editable. The implementation guidance is framework-neutral; examples use TypeScript.

## Adapt to your project
User and situation:
Input example:
Expected visible result:
Non-goals:
Ownership and data boundary:
Budget and constraints:

## Acceptance criteria
- [ ] Blank and oversized input fail before a model call.
- [ ] Unknown categories, malformed replies, and refusals never become successful suggestions.
- [ ] Duplicate concurrent submissions cause one dispatch.
- [ ] Uncertain calls retain cost reservations.
- [ ] The user can recover without losing the original ticket.
- [ ] Model quality is reported separately from mocked software tests.

## Record a case
Given:
When:
Then:
Evidence:

## Workflow checkpoints
### 1. Write a contract you can test
Output: feature-brief.md and five input/expected-outcome fixtures.
Check: An ambiguous ticket can return needs-review without inventing an answer.

### 2. Build a deterministic slice first
Output: A working local request-to-screen path using a mock provider.
Check: The interface completes the happy path with no API key and preserves input after a simulated failure.

### 3. Connect a bounded model request
Output: A provider adapter with an explicit error contract and configuration checklist.
Check: Malformed output cannot reach the suggestion UI as a successful response.

### 4. Make retries safe
Output: A request ledger and a concurrency test showing one dispatch for a duplicated request.
Check: Two concurrent identical requests create one operation and one provider call.

### 5. Evaluate usefulness and failure behavior
Output: evaluation.md with reproducible cases, failure analysis, and a release decision.
Check: The review records at least one realistic ambiguity and shows the action taken for every failed case.

### 6. Operate the feature
Output: An operations handoff with limits, owners, alerts, rollback, and a dated verification record.
Check: A provider outage leaves the user's ticket intact and offers a manual next action.

Included

acceptance.mdA completion checklist and verification record.

Sources & further reading

Official documentation supports the technical guidance. The scenario, prompts, and checklists are original implementation examples.

OpenRouter structured output ↗
Schema-constrained responses require a compatible model/provider. Validate results in your application too.
Playwright testing practices ↗
Use observable behavior, user-facing locators, and retrying assertions in browser tests.

Download acceptance.md ↓

Preview file

acceptance.md

# Ship one AI feature: acceptance

- [ ] Blank and oversized input fail before a model call.
- [ ] Unknown categories, malformed replies, and refusals never become successful suggestions.
- [ ] Duplicate concurrent submissions cause one dispatch.
- [ ] Uncertain calls retain cost reservations.
- [ ] The user can recover without losing the original ticket.
- [ ] Model quality is reported separately from mocked software tests.

## Verification record
Date / environment:
Revision:
Command or manual steps:
Expected / actual:
Outcome:
Unrun checks:
Known limitations:

handoff.mdTransfer the work with its assumptions and test evidence.Download handoff.md ↓

Preview file

handoff.md

# Implementation handoff

Task / owner:
Baseline / patch identity:
Contract version:
Changed files:
Decisions and assumptions:
Commands actually run and outcomes:
Manual journeys checked:
Known failures and unrun checks:
Integration dependencies:
Rollback notes:

Included

frame-a-feature.mdAgent skill: Turn an idea into a buildable brief. Save as frame-a-feature/SKILL.md in your agent's configured skills directory.Download frame-a-feature.md ↓

Preview file

frame-a-feature.md

---
name: frame-a-feature
description: "Define an implementable feature brief with observable acceptance cases. Use before building a new feature or narrowing an ambiguous product request."
---

# Turn an idea into a buildable brief

A scoped brief, an explicit non-goal list, and examples a developer can turn into tests.

## Inputs
The user problem, existing product, delivery constraints, and one example of success.

## Understand the existing product
Read relevant product notes and the current implementation. Name the user, triggering situation, present workaround, and desired result. Reuse decisions already made. Ask only about missing information that would materially change the implementation.

## Make the slice testable
Write one happy-path example using concrete input and expected visible output. Add the most consequential failure and repeat-action cases. Distinguish missing information from a chosen default. Define what is deliberately excluded from this iteration.

## Produce the handoff
Return: problem; example journey; input/output contract; affected screens and states; ownership/storage boundary; acceptance cases; unknowns. Each acceptance case must contain Given, When, and Then. Avoid specifying a framework or paid service unless the project requires it.

## Check the brief
A reader must be able to determine whether the example succeeded without asking what 'good' means. If an unknown blocks implementation, identify the smallest decision needed. Do not turn the brief into authorization to publish, purchase, or change access.

## Example request
Use frame-a-feature to scope a source-linked reading list. Readers save a URL and return to it later. Keep the first version local; produce a brief and acceptance cases before implementation.

Included

build-bounded-ai.mdAgent skill: Build an AI feature with explicit failure behavior. Save as build-bounded-ai/SKILL.md in your agent's configured skills directory.Download build-bounded-ai.md ↓

Preview file

build-bounded-ai.md

---
name: build-bounded-ai
description: "Implement a server-side model integration with validated results, replay protection, bounded spending, and a deterministic mock. Use when adding an AI call to an existing application."
---

# Build an AI feature with explicit failure behavior

A reviewable integration with deterministic failure tests and a documented budget boundary.

## Inputs
An approved task, representative inputs, the repository, and the allowed model/provider configuration.

## Inspect before changing
Locate request validation, provider adapters, credentials, persistence, and existing test commands. State the response contract and authorized input sources. Do not add a second provider or silently broaden data sent externally.

## Separate model output from application decisions
Validate the request before a model call. Bound input bytes, output tokens, and elapsed time. Treat source text as untrusted data. Parse the result against a local schema and verify cited IDs belong to this request. A well-formed response is not factual verification; keep uncertain output as a draft.

## Handle cost and replay explicitly
Associate an idempotency key with an input hash. Repeated keys with different inputs fail. Reserve allowed cost atomically before sending the request, using the configured rate ceiling. A timeout may still have incurred cost; retain its reservation until usage is reconciled. Do not automatically retry ambiguous completion.

## Prove failure behavior
Use a deterministic adapter for valid output, malformed JSON, unknown citations, refusal, timeout, and duplicate requests. Record public response, stored state, and number of provider calls. Keep raw credentials and submitted user content out of logs. Report commands actually run and unresolved cases; do not describe a mock as a live-provider test.

## Example request
Use build-bounded-ai for a support-ticket triage endpoint. Suggest a category and rationale, keep it as a draft, and preserve the original text. Use the existing server framework and a mock provider first.

Included