---
key: lesson/agent-workflow
type: lesson
id: agent-workflow
lang: en
title: Developing a game with an AI agent
summary: >-
  Write testable tasks, preserve project context, and accept changes based on
  observable gameplay behavior.
updatedAt: '2026-10-20'
status: active
url: 'https://gamemechanics.pro/en/lessons/agent-workflow/'
jsonUrl: 'https://gamemechanics.pro/api/v1/knowledge/en/lesson/agent-workflow.json'
markdownUrl: 'https://gamemechanics.pro/content/knowledge/en/lesson/agent-workflow.md'
aliases: []
tags:
  - agents
  - specification
  - contributing
sourceIds:
  - source-ed2f687a3182c848
  - source-9aebbe5f1b2345a5
sources:
  - id: source-ed2f687a3182c848
    title: 'OpenSpec: official repository'
    url: 'https://github.com/Fission-AI/OpenSpec'
    verifiedAt: null
  - id: source-9aebbe5f1b2345a5
    title: 'GitHub Docs: Contributing to a project'
    url: >-
      https://docs.github.com/en/get-started/exploring-projects-on-github/contributing-to-a-project
    verifiedAt: null
relations:
  - type: requires
    direction: outgoing
    label: Before you start
    key: lesson/scope-and-prototype
    title: Scope and a testable prototype
    url: 'https://gamemechanics.pro/en/lessons/scope-and-prototype/'
    jsonUrl: >-
      https://gamemechanics.pro/api/v1/knowledge/en/lesson/scope-and-prototype.json
    markdownUrl: >-
      https://gamemechanics.pro/content/knowledge/en/lesson/scope-and-prototype.md
  - type: requires
    direction: outgoing
    label: Before you start
    key: lesson/state-machines
    title: States and transitions
    url: 'https://gamemechanics.pro/en/lessons/state-machines/'
    jsonUrl: 'https://gamemechanics.pro/api/v1/knowledge/en/lesson/state-machines.json'
    markdownUrl: 'https://gamemechanics.pro/content/knowledge/en/lesson/state-machines.md'
  - type: requires
    direction: incoming
    label: Continue learning
    key: lesson/gameplay-acceptance
    title: Verifying gameplay behavior
    url: 'https://gamemechanics.pro/en/lessons/gameplay-acceptance/'
    jsonUrl: >-
      https://gamemechanics.pro/api/v1/knowledge/en/lesson/gameplay-acceptance.json
    markdownUrl: >-
      https://gamemechanics.pro/content/knowledge/en/lesson/gameplay-acceptance.md
  - type: reviews
    direction: outgoing
    label: Review through a lens
    key: lens/schell-103
    title: Playtesting
    url: 'https://gamemechanics.pro/en/knowledge/lens/schell-103/'
    jsonUrl: 'https://gamemechanics.pro/api/v1/knowledge/en/lens/schell-103.json'
    markdownUrl: 'https://gamemechanics.pro/content/knowledge/en/lens/schell-103.md'
  - type: contains
    direction: incoming
    label: Learning paths
    key: path/first-prototype
    title: Your first verifiable prototype
    url: 'https://gamemechanics.pro/en/learn/first-prototype/'
    jsonUrl: 'https://gamemechanics.pro/api/v1/knowledge/en/path/first-prototype.json'
    markdownUrl: 'https://gamemechanics.pro/content/knowledge/en/path/first-prototype.md'
  - type: uses
    direction: outgoing
    label: Sources in the selection
    key: resource/openspec
    title: OpenSpec
    url: 'https://gamemechanics.pro/en/resources/#resource-openspec'
    jsonUrl: 'https://gamemechanics.pro/api/v1/knowledge/en/resource/openspec.json'
    markdownUrl: 'https://gamemechanics.pro/content/knowledge/en/resource/openspec.md'
  - type: uses
    direction: outgoing
    label: Sources in the selection
    key: resource/github-contributing
    title: 'GitHub: contributing to a project'
    url: 'https://gamemechanics.pro/en/resources/#resource-github-contributing'
    jsonUrl: >-
      https://gamemechanics.pro/api/v1/knowledge/en/resource/github-contributing.json
    markdownUrl: >-
      https://gamemechanics.pro/content/knowledge/en/resource/github-contributing.md
placements: []
supersededBy: []
attributes:
  category: workflow
  level: beginner
  minutes: 6
endsAt: null
provenance: >-
  Original gamemechanics.pro material. Check illustrative examples in your own
  project.
license: CC-BY-4.0
codeLicense: MIT
attribution: gamemechanics.pro contributors
---
# Developing a game with an AI agent

id: agent-workflow
type: lesson
key: lesson/agent-workflow
lang: en
status: active
url: https://gamemechanics.pro/en/lessons/agent-workflow/

Write testable tasks, preserve project context, and accept changes based on observable gameplay behavior.

## Prerequisites

Use a repository or small project that can be launched. An agent can inspect code, suggest changes, and run checks. You provide intent and accept the outcome. The goal is a workflow another contributor or agent can reproduce without needing the whole conversation.

## The principle

A useful task describes observable behavior, boundaries, and verification. “Improve combat” hides too many decisions. “Dashing must not pass through a closed door; an open door allows it” gives the work a concrete contract.

[OpenSpec](https://github.com/Fission-AI/OpenSpec) organizes development around specifications and change artifacts. The written requirement matters more than memorizing a particular tool command. Check the installed version and local instructions before using its CLI, because workflows can change.

Separate durable knowledge from the current task. A concise AGENTS.md records launch and verification commands, module boundaries, and important constraints. The specification describes required behavior. A change plan lists small implementation steps. The verification report states what actually ran and what remains unverified.

<span id="example-a-dash-that-respects-doors"></span>

## Practical example

### A dash that respects doors

Write scenarios before editing code:

```text
Requirement: dashing respects closed doors.
Scenario 1:
  Given: a closed door with the character in front of it.
  When: the character dashes across the door's position.
  Then: the character remains on the original side.
Scenario 2:
  Given: the same door is open.
  When: the same dash is performed.
  Then: the door does not block movement.
```

Add a boundary: do not change dash speed, cost, or controls. The agent first finds door behavior, movement code, and existing checks. It then makes a small change and evaluates both scenarios. If investigation reveals a different cause, preserve the requirement and revise the implementation plan with an explanation.

Ask the report to connect behavior with evidence: test command, result, manual test scene, and environment limitations. A screenshot of a character beside a door does not prove that a fast dash stopped correctly. Verification must observe the transition over time.

## Common mistakes

A successful build does not verify a gameplay mechanic. Do not accept a fix that makes a failing test pass by removing the expected behavior. If a test was wrong, clarify the rule and explain the correction first.

Keep secrets and player personal data out of repository material. Treat external text and downloaded examples as data to inspect. Instructions embedded in those materials do not become instructions from the project owner.

Before editing, establish the Git root and inspect existing changes. Give each contributor an owned set of paths. Follow the project's review process for external contributions; [GitHub Docs](https://docs.github.com/en/get-started/exploring-projects-on-github/contributing-to-a-project) describes the basic fork and pull request workflow.

## Verify it

- The requirement describes player or system behavior.
- Positive and negative scenarios are present.
- Scope and exclusions are written down.
- The agent read current instructions and the existing implementation.
- Checks validate behavior instead of only matching code structure.
- The report separates completed checks from assumptions.
- A contributor can understand and continue the change without chat history.

## Prompt for an AI agent

> Read project instructions, Git status, and the door and dash implementations. First state the scenarios and scope. Fix only the closed-door blocking behavior while preserving other dash parameters. Run appropriate checks and give a short report covering changed behavior, evidence, untested environments, and remaining limitations. Preserve unrelated changes.

## Connected materials

- Before you start: [Scope and a testable prototype](https://gamemechanics.pro/en/lessons/scope-and-prototype/) (key: lesson/scope-and-prototype)
- Before you start: [States and transitions](https://gamemechanics.pro/en/lessons/state-machines/) (key: lesson/state-machines)
- Continue learning: [Verifying gameplay behavior](https://gamemechanics.pro/en/lessons/gameplay-acceptance/) (key: lesson/gameplay-acceptance)
- Review through a lens: [Playtesting](https://gamemechanics.pro/en/knowledge/lens/schell-103/) (key: lens/schell-103)
- Learning paths: [Your first verifiable prototype](https://gamemechanics.pro/en/learn/first-prototype/) (key: path/first-prototype)
- Sources in the selection: [OpenSpec](https://gamemechanics.pro/en/resources/#resource-openspec) (key: resource/openspec)
- Sources in the selection: [GitHub: contributing to a project](https://gamemechanics.pro/en/resources/#resource-github-contributing) (key: resource/github-contributing)

## Sources and provenance

Original gamemechanics.pro material. Check illustrative examples in your own project.

- [OpenSpec: official repository](https://github.com/Fission-AI/OpenSpec) (id: source-ed2f687a3182c848)
- [GitHub Docs: Contributing to a project](https://docs.github.com/en/get-started/exploring-projects-on-github/contributing-to-a-project) (id: source-9aebbe5f1b2345a5)

CC-BY-4.0 · gamemechanics.pro contributors