| name | setup-workflow |
| description | Author a new WORKFLOW.md for a project. Walks the operator through tracker selection, credentials, state definitions, agent backend, workspace root, and language-aware hook generation. Produces a validated WORKFLOW.md. |
| version | 1.0.0 |
setup-workflow
Author a new WORKFLOW.md for a project. This is the first skill a fresh
operator runs.
When to use
- The operator has cloned Sinfonia and has no
WORKFLOW.md yet.
- An existing
WORKFLOW.md needs to be regenerated from scratch (e.g. the
tracker changed).
If you're upgrading an existing workflow with the four-state pattern, use
setup-state-machine instead.
Procedure
1. Tracker selection
Ask the operator: "Which tracker do you use?"
Offer three options: linear, jira-cloud, jira-server.
2. Credentials + live validation
Prompt for tracker credentials and validate them immediately via a tracker
API call. Show the operator their project's actual states so step 3 is
grounded in reality.
- Linear: prompt for
LINEAR_API_KEY (env var name). Confirm
echo $LINEAR_API_KEY | head -c 10 is non-empty. Probe with
curl -s -H "Authorization: $LINEAR_API_KEY" -d '{"query":"{ viewer { id email } projects(first: 5) { nodes { name } } }"}' https://api.linear.app/graphql and surface the project names + viewer
email back to the operator.
- Jira Cloud: prompt for
JIRA_API_TOKEN, JIRA_EMAIL, and the
Atlassian endpoint (e.g. https://yourorg.atlassian.net). Probe with
curl -s -u "$JIRA_EMAIL:$JIRA_API_TOKEN" "$JIRA_BASE/rest/api/3/project" and surface project keys.
- Jira Server / DC: prompt for
JIRA_PAT and the endpoint. Probe with
curl -s -H "Authorization: Bearer $JIRA_PAT" "$JIRA_BASE/rest/api/3/project".
If any probe fails, stop and surface the error to the operator. Do not
proceed to step 3 — the rest of the flow depends on knowing the project's
real state list.
3. Active vs terminal states
Walk the operator through which states are active (Sinfonia dispatches
an agent on them) vs terminal (Sinfonia ignores them). Use the state
list returned in step 2 as the menu.
Recommend:
- Active:
Todo, In Progress (and Needs Fixes if the state-machine
pattern is enabled later).
- Terminal:
Done, Cancelled, Closed.
4. Agent backend
Invoke the setup-agent-backend skill to choose and configure a default
agent backend. That skill returns the agent: (and optional llm:) block
to inline here.
5. State-machine pattern
Offer the recommended four-state pattern (Triage → Ready → Needs Fixes →
Human Review). If accepted, defer to the setup-state-machine skill for
state generation; if declined, fall back to a single-prompt config that
runs on every active state.
6. Workspace root
Ask for the path where Sinfonia will clone per-issue workspaces. Default:
./workspaces. Validate the path is writable.
7. Language detection + hooks
Inspect the project root for a recognizable language marker:
| File | Language | After-create hook | Before-run hook |
|---|
package.json | Node | npm install | npm test --silent |
pyproject.toml | Python | pip install -r requirements.txt (or poetry install) | pytest -q |
Cargo.toml | Rust | cargo fetch | cargo test --no-run |
go.mod | Go | go mod download | go test ./... |
If multiple markers exist, ask the operator which one to use. Render the
matching hooks template into the hooks: block.
8. Render
Render templates/workflow.md.liquid with the answers from steps 1–7.
Write the result to ./WORKFLOW.md in the project root.
9. Validate
Run sinfonia --check WORKFLOW.md. Exit codes (per Phase 5 §3.1):
| Exit | Meaning | Remediation |
|---|
| 0 | All checks passed | Continue to step 10. |
| 2 | YAML parse error | Template bug — re-render and re-validate. |
| 3 | Schema validation | Likely a missing required field; re-prompt the operator. |
| 4 | Template compile error | The generated prompt body has a bad Liquid reference. Fix the template. |
| 5 | Tracker auth missing | The env var from step 2 isn't set in the current shell. |
Do not commit until validation passes.
10. Commit
git add WORKFLOW.md && git commit -m "Add Sinfonia workflow".
Next steps
Recommend the operator run:
setup-bridge — wire sinfonia-bridge to the same tracker for the CI
feedback loop.setup-state-machine — upgrade to the four-state pattern if not chosen
in step 5.setup-telemetry — wire OpenTelemetry into both binaries.
Templates
templates/workflow.md.liquid — the WORKFLOW.md skeleton.templates/hooks-node.liquid, templates/hooks-python.liquid,
templates/hooks-rust.liquid, templates/hooks-go.liquid —
language-specific snippets for step 7.
Validators
validators/check-workflow.sh — wraps sinfonia --check WORKFLOW.md
and surfaces the exit code with a remediation hint.
AI-tool-free fallback
If the operator doesn't have an AI tool installed, they can run
sinfonia init for an equivalent (slightly slimmer) REPL flow.
