Summary

This release ensures agents use Linear credentials from your workflow.yaml, supporting multiple Stokowski instances across different Linear teams.

What's new

• Workflow-driven Linear credentials — Agent subprocesses now receive LINEAR_API_KEY, LINEAR_PROJECT_SLUG, and LINEAR_ENDPOINT as env vars sourced directly from your workflow.yaml config. This means agents (and their MCP servers) can interact with Linear using the same credentials as Stokowski — no reliance on shell environment variables. Run multiple Stokowski instances with different Linear teams and each agent gets the right credentials from its own config.

Changed

• workflow.yaml is the single source of truth — Removed .env.example. The setup guide now directs users to put their API key in workflow.yaml directly. The example workflow ships with api_key uncommented to encourage this pattern.
• Updated README intro to position Stokowski as building beyond Symphony.

Test plan

• Verify agents can post comments to Linear using credentials from workflow.yaml
• Verify MCP servers (e.g. @linear/mcp-server) receive LINEAR_API_KEY via subprocess env
• Verify multiple Stokowski instances with different workflow.yaml configs use separate credentials

🤖 Generated with Claude Code

Release v0.2.0

Stokowski v0.2.0 replaces the fixed staged pipeline with a configurable state machine and adds multi-runner support. This is a major architectural change — workflows are now defined as states with explicit transitions, supporting loops, branching, and reusable stages. Different states in the same pipeline can use different runners (Claude Code or Codex) and different models.

What's new

State machine workflows — Replace the rigid ordered pipeline with a configurable state machine defined in workflow.yaml. Each state has a type (agent, gate, or terminal), maps to a Linear state, and declares explicit transitions. Loops and cycles are now first-class — a rework can send an issue back to any earlier state, not just the previous one.

Multi-runner support — States can now use either Claude Code or Codex as the runner, configured per-state via the runner field. Use Opus for investigation, Sonnet for implementation, and Codex for an independent code review — all in the same run.

Three-layer prompt assembly — Prompts are now built from three layers: a global prompt (shared context for every turn), a stage prompt (per-state instructions), and an auto-generated lifecycle injection (issue metadata, rework context, recent Linear comments, transition instructions). Prompt files are pure Markdown with Jinja2 templating — no more YAML front matter in prompt files.

Structured state tracking — State transitions and gate decisions are tracked via structured HTML comments on Linear issues (<!-- stokowski:state {...} -->). This enables crash recovery — on restart, Stokowski reads the latest tracking comment to determine where each issue left off.

Gate protocol — Human review gates use explicit Linear states: "Gate Approved" advances to the next state, "Rework" sends the issue back to a configurable rework target. Gates support max_rework limits — when exceeded, the issue is escalated and left for human intervention.

New Linear API methods — Comment creation, comment fetching, and issue state mutation are now supported, enabling the gate protocol and lifecycle injection to read recent activity from Linear.

on_stage_enter hook — A new lifecycle hook that runs when an issue enters a new state, useful for state-specific setup.

Codex stall detection — The Codex runner now has the same stall detection and timeout handling as the Claude Code runner.

Fixes

• Fixed transition key mismatch — example config used success but the orchestrator expected complete
• Fixed Mermaid diagram rendering with <br/> for line breaks in node labels

Upgrade guide

This release changes how workflows are configured. The old WORKFLOW.md format (YAML front matter + Jinja2 prompt body in a single file) is still parsed for backward compatibility, but the new workflow.yaml + prompts/ directory structure is strongly recommended.

To migrate:

1. Rename your config file. Copy your YAML front matter from WORKFLOW.md into a new workflow.yaml file. Or start fresh from workflow.example.yaml.

2. Add linear_states mapping. The old active_states and terminal_states lists on TrackerConfig are removed. Replace them with the new linear_states section:

   linear_states:
    active: "In Progress"
    review: "Human Review"
    gate_approved: "Gate Approved"
    rework: "Rework"
    terminal: ["Done", "Closed", "Cancelled"]

3. Add the new Linear states. In your Linear team workflow settings, add "Human Review", "Gate Approved", and "Rework" as custom states under "In Progress".

4. Define your state machine. Replace the single prompt body with a states section defining your pipeline. Each agent state points to a prompt file in prompts/. See workflow.example.yaml for a full example.

5. Split your prompt into files. Move your prompt template from WORKFLOW.md into separate files under prompts/ — one per state, plus an optional global.md for shared context. Prompt files no longer need YAML front matter. See the prompts/*.example.md files for reference.

6. Update Jinja2 variables. Template variables have changed: {{ issue.identifier }} is now {{ issue_identifier }}, {{ issue.title }} is now {{ issue_title }}, etc. The lifecycle injection now handles transition instructions automatically — you no longer need to tell agents which Linear state to move to.

Initial release. Stokowski is a Python daemon that orchestrates Claude Code agents driven by Linear issues — a Claude Code adaptation of OpenAI's Symphony.

Point it at a Linear project, write a WORKFLOW.md with your agent prompt and config, and Stokowski will pick up issues, spin up isolated workspaces, and run Claude Code agents against them — handling retries, multi-turn sessions, and state reconciliation automatically.

Requirements: Python 3.11+, Claude Code CLI, a Linear API key.