Task specifications

Task specifications are optional Markdown briefs for work that benefits from stable goals, constraints, and acceptance criteria. They do not require a parser or a specific AI runtime. Store reusable templates under .ai/tasks/templates. You can copy a template into an issue, a pull request, an AI conversation, or a temporary task file.

Choose a template

Template	Use it for
`.ai/tasks/templates/feature.md`	New user-visible or developer-facing behavior
`.ai/tasks/templates/bugfix.md`	Reproducible defects and regressions
`.ai/tasks/templates/refactor.md`	Structural improvements that preserve external behavior

Each template links to a matching workflow under .ai/workflows.

Required context

A useful specification contains:

Goal: the observable outcome, not an implementation guess.
Context: owning area, current behavior, related paths, and affected platforms.
Constraints: interfaces, boundaries, compatibility, and behavior that must remain stable.
Acceptance criteria: independently verifiable outcomes.
Validation: targeted commands and manual checks.

Make repository paths explicit. An instruction such as “update the profile flow” is ambiguous; a path such as apps/mobile/app/(app)/(tabs)/profile.tsx gives the AI a concrete starting point.

Example

# Feature task

Follow `.ai/workflows/feature.md`.

## Goal

Allow a signed-in user to replace their profile photo.

## Context

- Owning area: `apps/mobile`
- Related files:
  - `apps/mobile/app/(app)/(tabs)/profile.tsx`
- Platforms: iOS and Android
- Current behavior: the profile photo cannot be changed

## Constraints

- Keep the route focused on composition.
- Reuse existing storage and logging helpers.
- Preserve cancellation behavior.

## Acceptance criteria

- [ ] Selecting a supported image updates the preview.
- [ ] Cancelling leaves the current image unchanged.
- [ ] Relevant tests and `bun run verify` pass.

## Validation

- Automated checks:
  - `<targeted project test>`
  - `bun run verify`
- Manual checks:
  - Replace and cancel a profile image on iOS and Android.

Use a task with an AI tool

Ask your AI tool to read the task, AGENTS.md, and .ai/README.md, then follow the linked workflow. Review its plan before allowing implementation for broad or ambiguous work.

Keep credentials, customer data, private endpoints, and machine-specific paths out of committed task files.

Configuration

AI

Generators

Packages

Choose a template

Required context

Example

Use a task with an AI tool

​Choose a template

​Required context

​Example

​Use a task with an AI tool

Choose a template

Required context

Example

Use a task with an AI tool