---
name: ambler-spec
description: Creates or updates a Markdown specification file for an Ambler walk in the specs/ directory. Use this whenever a user wants to document, plan, or describe a walk — including "write a spec", "document this walk", or "plan out the steps" — even before any code exists.
metadata:
  author: leandro
  version: "1.1"
---

# Ambler Specification

This skill guides you in creating a Markdown specification file (`specs/<walk-name>.md`) for an Ambler walk. These specs describe the program's shared state and the logic for each step (node) in the state machine.

## Instructions

### 1. Identify the Walk's Name and Purpose

- If not provided, ask the user for the name and a brief description of the walk.
- The file should be named `specs/<name>.md`.

### 2. Determine the Shared State

- Identify the data structure passed between nodes.
- Describe it under a `## Shared State` heading.

### 3. Map the Steps (Nodes)

- Identify all nodes in the walk.
- For each node, create a `### <Node Name>` subsection under `## Steps`.
- Describe:
  - Its role (e.g., "This is the initial step").
  - Its logic (what it does).
  - Its transitions (what conditions lead to which next step).

### 4. Format the Markdown

Follow this exact format:

```markdown
# Program Specifications

<Brief description of the program and its purpose.>

## Shared State

<Description of the state object shared across the nodes.>

## Steps

### <Node Name 1>
- <Role — e.g., "This is the initial step.">
- <Logic — e.g., "Prompts the user to enter X.">
- <Transitions — e.g., "If valid, proceeds to `NEXT`. If invalid, proceeds to `START`.">

### <Node Name 2>
- <Role.>
- <Logic.>
- <Transitions.>

### <Node Name N>
- <Role — e.g., final step.>
- <Logic.>
- <Termination — e.g., "Displays result and terminates.">
```

### 5. Write the File

Use the Write tool to create `specs/<name>.md`.

## Guidelines

- **Node name casing**: Use Title Case for headings (`### Count`) and backtick-quoted ALL_CAPS for references in transition descriptions (`` `COUNT` ``).
- **Clarity**: Describe *what* the program does, not *how* the code implements it.
- **Consistency**: If `walks/<name>.ts` already exists, ensure the spec reflects the implementation. If it doesn't, treat the spec as a blueprint.
- **No extra sections**: Stick to `# Program Specifications`, `## Shared State`, and `## Steps` — no additional top-level sections unless the walk clearly requires them.

## Example Specification

```markdown
# Program Specifications

This program is a simple counter application.

## Shared State

The shared state is an integer representing the current count.

## Steps

### Start
- This is the initial step of the application.
- Prompts the user to enter a starting number for the count.
- If the number entered is valid, it proceeds to `COUNT`.
- If the number entered is invalid, it displays an error message and proceeds to `START`.

### Count
- Prints the current count and increments the counter.
- Transitions to `COUNT` or to `STOP`.

### Stop
- Displays the final count and terminates.
```