playbook

Imported from izantech/lineup (.lineup-core/snapshots/skills/playbook/SKILL.md). Install upstream with npx skills add izantech/lineup --skill playbook. Copyright stays with the author.

You are the orchestrator for the Lineup playbook manager. A project's playbook is its collection of tactic files -- reusable workflow definitions stored as YAML in .lineup/tactics/. Each tactic is a play: a named sequence of agent stages that the kick-off skill can discover and run. This skill walks the user through creating, editing, importing, or deleting plays in their project's playbook.

Step 1 -- Discover

Gather the current state before presenting options to the user.

1a. Read the tactic schema

Read templates/tactic.yaml from this plugin's directory (two levels up from this skill file). Extract the field definitions, available stage types, and available agents. Use this as the validation reference throughout the session.

The canonical field reference:

1b. Read example tactics

Read all .yaml files from the plugin's examples/tactics/ directory. These serve as formatting references and starting-point templates for new tactics.

1c. Read existing project tactics

Check if .lineup/tactics/ exists in the current working directory. If it does, read all .yaml files in that directory and parse their names and descriptions.

1d. Read built-in tactics

Read all .yaml files from the plugin's tactics/ directory. These are built-in tactics shipped with the plugin. Note them separately -- they cannot be edited or deleted through this skill, but the user can override them by creating a project tactic with the same name.

1e. Present inventory

Display a summary of what was found:

Playbook inventory:

Project tactics (.lineup/tactics/):
  - brownfield-docs -- Generate missing documentation for an existing codebase
  - api-feature -- Add a new API endpoint or service

Built-in tactics (plugin):
  - explain -- Get a clear explanation of any project component

Example templates available:
  - brownfield-docs, api-feature, targeted-refactor, bug-triage, full-feature

If no project tactics exist, show "No project tactics defined yet."

Step 2 -- Choose mode

Use AskUserQuestion to present the available modes:

Question: "What would you like to do?"
Options:
  1. Create a new tactic from scratch
  2. Import from an example template
  3. Edit an existing tactic
  4. Delete an existing tactic

If no project tactics exist, omit options 3 and 4.

Mode: Import

If the user chooses Import:

1. Present the example templates with descriptions using AskUserQuestion.
2. After selection, read the chosen example file from examples/tactics/.
3. Show the full YAML content and ask: "Use this as-is, or customize it?"
4. If as-is: copy to .lineup/tactics/<name>.yaml and skip to Step 8 (Write).
5. If customize: load the example content as the starting state and proceed to Step 3 for name/description editing, then Step 4 for stage editing, and so on.

Mode: Edit

If the user chooses Edit:

1. Present the list of project tactics using AskUserQuestion.
2. Read the selected tactic file.
3. Show the current YAML content.
4. Ask which aspect to edit using AskUserQuestion:

Question: "What would you like to change?"
Options:
  1. Name and description
  2. Stages (add, remove, reorder)
  3. Verification criteria
  4. Variables
  5. Edit everything (walk through all steps)

5. Jump to the relevant step(s). For option 5, proceed through Steps 3-7 in order with the current values pre-populated as defaults.

Rename handling: If the user changes the tactic name in Step 3, note the old name. In Step 8, write the new file and delete the old one.

Mode: Delete

If the user chooses Delete:

1. Present the list of project tactics using AskUserQuestion.
2. Show the selected tactic's full YAML content.
3. Ask for confirmation: "Delete .lineup/tactics/<name>.yaml? This cannot be undone."
4. If confirmed, delete the file.
5. If the .lineup/tactics/ directory is now empty, delete the directory.
6. Report the result and end the session.

Mode: Create

Proceed to Step 3.

Step 3 -- Name and description

Name

Ask the user for a tactic name using AskUserQuestion with a free-text option.

Validation rules:

• Must be kebab-case: lowercase letters, digits, and hyphens only
• Must not start or end with a hyphen
• Must be 3-50 characters
• Must not conflict with an existing project tactic name (unless editing)
• Must not conflict with a built-in tactic name (warn if it does -- the project tactic will override the built-in)

If validation fails, explain the rule and ask again.

Description

Ask the user for a description. Guide them: "One to three sentences explaining what this tactic does and when to use it."

Validation rules:

• Must be non-empty
• Should be 10-200 characters (warn if outside range but do not block)

Store both values for the preview in Step 7.

Step 4 -- Stage builder

This is the core of the skill. Walk the user through building an ordered list of stages.

Conventional pairings

Before starting, present the recommended stage patterns:

Common stage patterns:

  Research-first (most common):
    research -> plan -> implement -> verify

  Quick fix (skip research):
    plan -> implement -> verify

  Documentation pass:
    research -> plan -> document

  Full pipeline with controls:
    research (optional) -> plan (gate: approval) -> implement -> verify -> document (optional)

  Investigation only:
    research -> explain

You can use any combination of stages. These are starting suggestions.

Use AskUserQuestion to ask if the user wants to start from one of these patterns or build from scratch:

Question: "Start from a common pattern or build from scratch?"
Options:
  1. Research-first (research -> plan -> implement -> verify)
  2. Quick fix (plan -> implement -> verify)
  3. Documentation pass (research -> plan -> document)
  4. Full pipeline with controls
  5. Investigation only (research -> explain)
  6. Build from scratch

If a pattern is selected, pre-populate the stages list with the pattern's stages and proceed to let the user customize each one.

Stage loop

For each stage (whether pre-populated or added from scratch), collect four pieces of information:

1. Stage type and agent

Use AskUserQuestion to ask for the stage type. Show the conventional type-agent pairing as the default:

Question: "Stage 1 -- which type?"
Options:
  1. research (agent: researcher)
  2. plan (agent: architect)
  3. implement (agent: developer)
  4. verify (agent: reviewer)
  5. document (agent: documenter)
  6. clarify (agent: researcher)
  7. explain (agent: teacher)
  8. clarification-gate (agent: architect)

The conventional type-agent pairings are:

After selecting the type, use the conventional agent as the default. If the user wants a different agent, allow any valid agent name.

2. Custom prompt (optional)

Ask: "Add a custom prompt for this stage? This gives the agent specific instructions for this tactic."

If yes, ask the user to provide the prompt text. Guide them: "Describe what the agent should focus on in this stage. Use ${variable_name} to reference variables you will define later."

If no, the stage uses the agent's default behavior.

3. Optional flag

Ask: "Make this stage optional? (The orchestrator will ask the user whether to run it.)"

Default: No.

4. Gate

Ask: "Add an approval gate after this stage? (The orchestrator will pause for user approval before proceeding.)"

Default: No.

Adding more stages

After each stage is defined, ask:

Question: "Stage list so far: [research -> plan -> implement]. Add another stage?"
Options:
  1. Add another stage
  2. Done -- move to verification

Show the current stage list in the question so the user can see the flow.

Editing pre-populated stages

When working from a pattern, present each pre-populated stage and ask: "Keep as-is, customize, or remove?"

Question: "Stage 1: research (agent: researcher, no custom prompt). Keep, customize, or remove?"
Options:
  1. Keep as-is
  2. Customize this stage
  3. Remove this stage

If the user chooses to customize, walk through the four questions above (prompt, optional, gate). The type and agent are already set but can be changed if the user asks.

After reviewing all pre-populated stages, offer to add more.

Step 5 -- Verification criteria

Ask the user to define verification criteria -- human-readable checks that the reviewer (or orchestrator) evaluates after execution.

Question: "Add verification criteria? These are checked after the tactic runs."
Options:
  1. Yes, add criteria
  2. Skip verification (not recommended if you have a verify stage)

If yes, prompt for criteria one at a time:

Question: "Enter a verification criterion (e.g., 'All new endpoints have test coverage'):"
Options:
  1. [free text]

After each criterion, ask:

Question: "Criteria so far: ['All tests pass', 'No lint errors']. Add another?"
Options:
  1. Add another criterion
  2. Done

Validation:

• Each criterion must be a non-empty string
• Warn if stages include a verify type but no criteria are defined

Step 6 -- Variables

Ask the user if the tactic needs variables -- values that the orchestrator prompts for before execution and substitutes into stage prompts using ${variable_name}.

Question: "Define variables? These let users customize the tactic at runtime."
Options:
  1. Yes, add variables
  2. No variables needed

If yes, collect for each variable:

1. Name: Must be snake_case, 2-30 characters, letters/digits/underscores only, must start with a letter.

2. Description: A human-readable description shown to the user when prompted. Must be non-empty.

3. Default value: The default value offered when prompting. Can be empty string.

After each variable, ask to add another or finish.

Cross-reference validation

After all variables are defined, validate that every ${variable_name} reference in stage prompts corresponds to a defined variable. If a prompt references an undefined variable:

• List the undefined references
• Ask the user whether to: (a) define the missing variables now, or (b) remove the references from the prompts

Also check the reverse: warn if any defined variable is never referenced in any stage prompt. Ask whether to keep or remove unused variables.

Step 7 -- Validate and preview

Schema validation

Check the complete tactic against the schema:

1. name is present and valid kebab-case
2. description is present and non-empty
3. stages is a non-empty list
4. Each stage has a valid type and agent
5. optional values are boolean if present
6. gate values are approval if present
7. Variable names are valid snake_case
8. All ${variable_name} references in prompts resolve to defined variables

Report any errors. If errors exist, loop back to the relevant step to fix them.

Semantic validation

Check for logical issues and warn (do not block):

• A verify stage exists but no verification criteria are defined
• verification criteria exist but no verify stage is defined (orchestrator will present them as a manual checklist -- note this to the user)
• An implement stage exists without a preceding plan stage
• A plan stage has no gate: approval (recommended for user control)
• Variables are defined but never referenced in prompts
• The first stage is implement (unusual -- typically research or plan comes first)

Preview

Generate the complete YAML and present it to the user. The YAML must follow the exact formatting from the example tactics:

# <name> -- <first sentence of description>.
# <remaining description lines as comments, wrapped at ~80 chars>.

name: <name>
description: |
  <description text>

variables:
  - name: <variable_name>
    description: "<description>"
    default: "<default_value>"

stages:
  - type: <type>
    agent: <agent>
    prompt: |
      <prompt text, indented 6 spaces>
  - type: <type>
    agent: <agent>

verification:
  - "<criterion 1>"
  - "<criterion 2>"

Formatting rules (match the example tactics exactly):

• Header comment: # <name> -- <first sentence of description>. followed by additional comment lines wrapping the rest of the description and context
• Blank line after header comments
• Top-level keys in order: name, description, variables, stages, verification
• Blank line between each top-level key
• description uses pipe-block (|) with 2-space indent
• Stage list uses 2-space indent for the list marker, 4-space indent for stage fields
• prompt uses pipe-block (|) with 6-space indent for content
• verification items are double-quoted strings
• variables items use unquoted name, double-quoted description, double-quoted default
• Omit optional and gate fields when they are false/absent (do not write optional: false)
• Omit verification section entirely if no criteria are defined
• Omit variables section entirely if no variables are defined
• Trailing newline at end of file

Ask the user to confirm:

Question: "Write this tactic to .lineup/tactics/<name>.yaml?"
Options:
  1. Yes, write it
  2. Go back and make changes
  3. Cancel

If "Go back", ask which step to revisit and jump there. After changes, return to Step 7 for re-validation and preview.

Step 8 -- Write

Create the directory

If .lineup/tactics/ does not exist, create it.

Write the file

Write the tactic YAML to .lineup/tactics/<name>.yaml.

Handle rename (edit mode)

If the tactic was renamed in edit mode (old name differs from new name):

1. Write the new file first
2. Delete the old file (.lineup/tactics/<old-name>.yaml)
3. Report both actions

Confirm

Report the result:

Tactic written to .lineup/tactics/<name>.yaml

You can run it with: /lineup:kick-off <name>

If this is a new tactic, briefly remind the user that /lineup:kick-off will auto-discover it.

Rules

• Never modify plugin example files -- examples in examples/tactics/ are read-only references. Only write to .lineup/tactics/ in the project directory.
• Never modify built-in tactics -- files in the plugin's tactics/ directory are read-only. The user can override them by creating a project tactic with the same name.
• Always preview before writing -- show the complete YAML and get explicit confirmation before writing to disk.
• Support rename in edit mode -- if the name changes, write the new file and delete the old one.
• Use exact YAML formatting from examples -- header comments, pipe-blocks, indentation, quoting, and field order must match the example tactics.
• Validate all inputs -- names (kebab-case), variable names (snake_case), agent names, stage types, and variable cross-references.
• Warn but do not block on semantic issues -- missing verification criteria, unused variables, and unconventional stage ordering are warnings, not errors.
• Always use AskUserQuestion for user decisions -- never assume choices. Provide concrete options with a free-text fallback where appropriate.
• Omit default values -- do not write optional: false or gate: null to the YAML. Only include fields with non-default values.