Prompts & workflows

This part of the manual is about words that become behaviour. Wire Linear, GitHub Actions, and a cloud agent perfectly, and you can still lose the plot when instructions live only in chat, a SaaS text box, or someone’s memory. Mature Ship adoptions treat prompts like workflow YAML: git is the source of truth, pull requests are the review room, and “we fixed it in Cursor” is a waypoint—not the system of record.

Framework says what must stay true. Tools names the adapters. Here we describe how prompt text evolves without turning the repo into a graveyard of one-off hacks—and how that evolution starts small on purpose.

Jump: Start with a skeleton · State flow (ElMundi) · Full prompts/cloud-agent/ files · Workflow patterns

Concrete filenames, cron minutes, and secrets stay in Examples → Reference org. This page names habits and shows real prompt files from this package (the same ones ElMundi wires in production).

The mistake everyone makes is the same mistake as big-bang automation: sitting down to write the perfect prompt in one session. You produce a wall of rules—half of them untested, half of them wrong for your repo—and no story for how they stay true when the board, the tests, or the product changes next month. The model will happily obey contradictory instructions; the failure mode is not disobedience, it is confidence.

We do the opposite. You ship a base: enough structure that a headless run can attempt the job under clear guards (tracker state, branch contract, what “done” means for this role, when to stop). If the first draft is longer than a screen, cut it. Depth is not virtue; testability is. The grid and the ticket timeline will teach you where the text lied; your job is to listen and grow the prompt in thin layers, each layer merged like code.

A minimum prompt does not need poetry. It needs four kinds of clarity, usually in plain bullets:

Scope — one sentence on what this role is allowed to do—and what is explicitly out of bounds (no merge, no promote, no drive-by refactors).

Preconditions — which project, column or state, and labels must be true before the agent acts. If this is missing, you will debug “mood” instead of guards.

Reporting — how the run leaves traces: comment marker pattern, PR title shape, branch name. Auditability is not optional; it is how the next human knows what happened.

Stops — when to pause and ask a human instead of guessing: hollow ticket, ambiguous acceptance criteria, tests failing for reasons outside this change.

Everything else—edge cases, style guides, long examples—is seasoning. Add seasoning after at least one real run proves which corner actually hurts.

The second step is not “brainstorm more rules.” It is: let the schedule run once (or fire workflow_dispatch for a single issue) and watch the run end-to-end. Note what the agent did, skipped, or misunderstood; pair ticket timeline with workflow run so the story is reconstructable. If you cannot pair them, stop—you are not ready to tune wording; your audit trail is broken.

Then fix interactively at human speed: inline agent, small patch, small explanation. One misunderstanding per iteration. Prefer a concrete example from this repository over abstract lecture. If the real fix is a policy change—new label, tighter pick—change tracker or pick before you add another paragraph to the prompt.

The interactive fix is not durable until it lives in prompts/cloud-agent/*.md (for scheduled Cursor Cloud runs). Open a PR, link the ticket that exposed the gap, and merge to the branch your schedules checkout—usually main. Reviewers should ask: does this rule overfit one weird ticket, or does it generalise? Chat is fast; merged markdown is what cloud-agent-launch.mjs actually reads.

!!! note If you skip the PR, the next cron tick will happily repeat the bug. That is not the model forgetting—it is you forgetting where the source of truth lives.

If the prompt lives only in a vendor UI, you cannot diff it, blame it, or roll back when a clever rule blows up production. You also cannot prove what text ran last Tuesday. Treat prompts as config code—same review bar as *.yml.

Often the bug is not the prompt—it is what got picked or how the agent was launched.

1. Fix pick / cron / project guards if the wrong work is selected.
2. Fix launch wiring if the agent never sees the right branch, ref, or secrets.
3. Then tighten prompt wording.

See Workflow patterns for intent; Workflows catalog for filenames in the reference org.

No user story — “be smart” is not a requirement. Silent retries without ticket comments destroy auditability. One mega-prompt for every role makes diffs unreadable; split by role file (intake, developer, …). Pasting a novel from Notion guarantees drift the day someone edits Notion. Testing only in chat — chat lies cheerfully; CI and scheduled runs tell the truth.

The habit underneath is almost boring on purpose: boring survives reality. When reality punches a hole, fix interactively once, then write the lesson back so headless runs do not depend on who is online.

The diagram is the pretty view of the same wiring spelled out in Examples → ElMundi → SDLC scheduled: human-only Backlog, automation picking only Todo in the delivery project, four roles on the even-hour UTC grid (:10 intake → :25 clarification → :40 BA → :55 developer), and developer as the only role that moves a card to In Progress after pick + cli start + the fix/<ISSUE>-auto branch. The legend box on the diagram names the label-shaped milestones in plain language (without colons in edge labels, so the graph stays readable).

Columns (canonical names for that wiring):

Label-shaped milestones on the happy path (simplified): intake may set needs:clarification or stage:intake; after BA, ready:developer on Todo is the gate for the developer pick. Exact pick scripts and filters live beside the workflows in the example chapter—this page stays the story; that chapter stays the receipts.

Daily audit roles (tech / QA / security) use separate Linear projects and no delivery-queue pick; see Daily audits.

This section is one page inside one page: the map below plus the complete markdown files as they ship in the repository—no ellipses, no “see repo for the rest.” The Next.js manual expands the same --8<-- includes at render time so the site and git cannot silently diverge.

Placeholders such as {{ISSUE}}, {{BASE}}, and {{SKILLS_CONTEXT}} are filled by your project launcher/runtime at run time; treat them as part of the contract, not as typos.

How to change them safely: Start with a skeleton. Optional A-series drafts under prompts/catalog/ are human reference only; Your launcher should read prompts/cloud-agent/—promote edits there when scheduled runs should inherit them.

Adding a new role: decide which project receives output, which schedule fires it, what guards stop the run, and what artefact proves success. If you cannot answer, you are adding noise—not a prompt.

Skills under .cursor/skills/ are embedded by the launch path—keep them short; link out to this manual for depth. Onboarding playbooks live in prompts/onboarding/ — see Adoption → Overview.

Cross-cutting rules for every headless role (queue boundaries, Linear as the human channel, idempotency, branch contract, audit markers).

• SDLC queue: GitHub pick scripts only take tickets in Todo and in the Linear project configured by LINEAR_SDLC_PROJECT_ID or LINEAR_SDLC_PROJECT_NAME. Backlog is for manual triage — automation does not pick it up until you move the card to Todo.
• Linear: The single channel with humans is comments on the ticket in Linear. Do not spam: one substantive comment per pass; end with [GitHub SDLC:{{ROLE}}].
• IDEMPOTENCY: Before making changes, re-read the ticket (and latest comments). If work for this role is already done (required labels/description/status), exit without changes and without a comment.
• GitHub schedule: The same ticket can re-enter pick after ~2h. If the latest comment with [GitHub SDLC:{{ROLE}}] already reflects the current state and there are no new inputs — do not duplicate updates or comments.
• Do not merge PRs. Do not move to Done without explicit human approval.
• LINEAR_API_KEY: Must be available to the agent (Cursor Cloud → Secrets / env for the repository). Update Linear via API or the official client. If the key is missing — one comment [LINEAR-DRAFT] with JSON/text of what to apply manually.
• Skills: Context from .cursor/skills appears below — follow it for Bunny, deploy, self-heal, etc., when the task touches those areas.
• One ticket — one open PR from SDLC: branch fix/{{ISSUE}}-auto (issue key from the ticket, e.g. ENG-12 → fix/ENG-12-auto; see runtime/scripts/cloud-agent-launch.mjs). Do not create a parallel feature/…-auto branch for the same ticket — that duplicates work; if two PRs already exist, do not merge both: keep the current one and close the other.
• Dev / prod / deploy: org-specific hosts, runbooks, and workflow names live in repository settings and documentation/examples (reference deployment). Follow your team’s documented pre-release and promote process — do not assume a particular domain or image name.
• Daily audit roles (tech-architect, qa-architect, security-officer): do not create tickets without verifiable facts; dedupe against open issues in target Linear projects. Comment marker: [GitHub SDLC daily-audit:…] (see documentation/examples / operator docs when present).

{{SKILLS_CONTEXT}}

Role: Intake ({{ISSUE}})

{{BASE}}

• Title: {{TITLE}}
• Description: {{DESCRIPTION}}

The ticket is already in Todo and in the pre-release project — that means automation may pick it up (do not touch Backlog).

1. Classify: feature / bug / refactor / infra / improvement.
2. Check completeness: goal, problem, expectation, AC, constraints.
3. If information is missing: one comment with numbered questions, label needs:clarification, keep status Todo (the ticket is already in the working column for automation).
4. If enough: shape the description (Problem, Goal, Expected Behaviour, Scope, AC, Non-goals, Risks), label stage:intake, status Todo (next — BA).

Brief comment on what you did. End with: [GitHub SDLC:intake]

Role: Clarification follow-up ({{ISSUE}})

{{BASE}}

• Title: {{TITLE}}
• Description: {{DESCRIPTION}}

1. Read comments (newest first). If the latest reply is from the agent and the human has not yet answered the questions — do nothing.
2. If the human resolved the questions: update the description, remove needs:clarification, ensure stage:intake, status Todo.
3. If questions remain — one short follow-up comment.

One pass — at most one comment when needed. End with: [GitHub SDLC:clarification]

Role: BA / Spec ({{ISSUE}})

{{BASE}}

• Title: {{TITLE}}
• Description: {{DESCRIPTION}}

1. Add specification: Feature Description, User Stories, AC, Edge Cases, Impacted Components, Technical Notes, Test Plan.
2. If scope is huge — create sub-issues and do not set ready:developer without review.
3. Otherwise: ready:developer, status Todo.

One short summary comment. End with: [GitHub SDLC:ba]

Role: Developer ({{ISSUE}})

{{BASE}}

• Title: {{TITLE}}
• Description: {{DESCRIPTION}}

1. Linear status should already be In Progress (set by GitHub). The branch for this run is provided by the API as **fix/{{ISSUE}}-auto** — work only in that branch. Do not create **feature/{{ISSUE}}-auto** or duplicate work in a second branch: that leads to two PRs for one ticket and manual cleanup.
2. Implement per description and AC.
3. Tests: add or update unit/integration for new logic; if UX or a critical flow changes — update or add e2e (Playwright). Do not stop at a green test alone: new behaviour should be covered by checks; if not, explain clearly in the PR/Linear comment why (rare case).
4. cd website: run npm run lint, typecheck, test, build, test:e2e:smoke (chromium-desktop where applicable) — all relevant targets must pass before opening the PR.
5. Commit message: fix({{ISSUE}}): … or feat({{ISSUE}}): …
6. Before opening a PR: in GitHub check there is no open PR for this ticket already (body/title with Closes {{ISSUE}}, branch fix/{{ISSUE}}-auto or similar). If one exists — do not open a second: push to the existing branch or one Linear comment with the PR link.
7. Open exactly one PR with Closes {{ISSUE}} (if none open yet). After the PR — status In Review in Linear.

One ticket comment with the PR link (one per pass). End with: [GitHub SDLC:developer]

Role: Workflow self-heal / pipeline autofix ({{ISSUE}})

{{BASE}}

Use {{ISSUE}} only for one short status comment after a successful pass (after the PR). Do not inflate the ticket description.

• Title: {{TITLE}}
• Description (excerpt): {{DESCRIPTION}}

1. A JSON report from workflow-self-healer (issues, recommendations) may be attached below in the prompt. Rely on facts and on the workflow-self-healer skill.
2. If the report is empty or issues are already fixed on **main** — exit with no changes, no PR, and no Linear comment.
3. Otherwise apply minimal fixes; run locally what makes sense (lint/test/targeted script).

Before any commits/PR:

1. Open PRs: check GitHub for open PRs related to the same symptom (branches cursor/workflow-self-heal-*, titles/changelog mentioning preview/probe/Linear/self-heal). If a PR already exists with the same fix or overlapping scope — do not create a second: comment on the existing PR or stop with one short Linear note that work is already in PR #N.
2. Linear comments: read the latest comments on {{ISSUE}}. If there is already a comment with [GitHub SDLC:workflow-self-heal] linking to an open PR from the last 72 hours and that PR is still open — do not post a duplicate or open a parallel PR without new facts in the report.
3. One outcome per pass: at most one new PR from this run. Do not split one fix across multiple PRs.
4. Developer/SDLC branches: do not collide with other active fix/*-auto SDLC branches or rename others’ artifacts.

After successful work:

1. One PR with a clear description. In Linear — at most one new comment: PR link + [GitHub SDLC:workflow-self-heal].

• Do not touch GitHub secrets / variables in code.
• Do not merge PRs.
• Do not spam Linear (no chains of “another update” without a new PR or new finding in the report).

Role: Tech Architect (daily audit) — {{ISSUE}}

{{BASE}}

This is not an SDLC ticket: no anchor (NONE). You analyze the repository (checkout on the agent branch).

• Project ID: {{TECH_DEBT_PROJECT_ID}}
• Name: {{TECH_DEBT_PROJECT_NAME}}
• Team: {{LINEAR_TEAM_KEY}}

Create new cards only in this project, status Backlog, when the rules below are satisfied.

1. From code and configs find real tech debt or architectural risk: duplication, layer-boundary violations, outdated patterns, risky architectural dependencies, unclear modules, “god” files — only with path reference (website/..., tools/...) and brief factual evidence (structure, imports, size, coupling), not vague wording.
2. Before creating a ticket: via Linear API (or MCP) check open issues in project {{TECH_DEBT_PROJECT_ID}} with label source:tech-architect or audit:auto. If the topic is already covered (same component/path/problem) — do not create a duplicate; if needed, one comment on the existing card with a new fact.
3. If this pass has no new, verifiable finding — do not create tickets and do not post Linear comments for a report. Finish with no PR (if a draft analysis branch is not needed — do not commit noise).
4. If there are findings: one issue per finding, specific title, description: context, file paths, why it matters, suggested direction (no made-up metrics). Labels: source:tech-architect, audit:auto, and improvement or tech-debt if they exist for the team.
5. One short summary only if you created or updated something: you may leave it in the last created issue’s description or skip duplicating.

Forbidden: inventing files, CVEs, numbers, or “best practices” not grounded in this repo.

End of any Linear comment (if you wrote one): [GitHub SDLC daily-audit:tech-architect]

Role: QA Architect (daily audit) — {{ISSUE}}

{{BASE}}

There is no anchor ticket (NONE). You review test coverage and test strategy quality in the repository (Playwright, unit, CI).

Put tech-debt cards about tests in the same tech-debt project:

• Project ID: {{TECH_DEBT_PROJECT_ID}}
• Name: {{TECH_DEBT_PROJECT_NAME}}
• Team: {{LINEAR_TEAM_KEY}}

Status for new issues: Backlog.

1. Find concrete gaps: critical user flows without e2e, missing regression checks, brittle selectors, duplicate scenarios, missing negative cases — always with path to file (website/tests/...) or to production code that is not covered.
2. Before creating a ticket: search project {{TECH_DEBT_PROJECT_ID}} for open issues with source:qa-architect or audit:auto for the same area (same spec/feature/route). Do not create duplicates.
3. If there are no new verifiable gaps — do not create anything in Linear and do not post a “checkbox” comment.
4. If there are gaps — one issue per meaningful unit (e.g. “add e2e for X”, not ten micro-tickets with one phrase). Description: AC as a checklist, links to files. Labels: source:qa-architect, audit:auto, and improvement if needed.

Forbidden: inventing spec files or CI failures that do not exist in the file tree.

End of comment (if you wrote one): [GitHub SDLC daily-audit:qa-architect]

Role: Security Officer (daily audit) — {{ISSUE}}

{{BASE}}

No anchor (NONE). A Snyk JSON report from CI may be attached below in the prompt — use it as the primary source for dependency vulnerabilities.

• Project ID: {{SECURITY_PROJECT_ID}}
• Name: {{SECURITY_PROJECT_NAME}}
• Team: {{LINEAR_TEAM_KEY}}

All new security issues go only here, status Backlog.

Map from Snyk / CVSS:

If the report has no vulnerabilities or the array is empty — do not create tickets.

1. Parse the Snyk JSON (if attached): for each unique package + vulnerability (id/CVE) combo, check there is no open issue in project {{SECURITY_PROJECT_ID}} with the same identifier in title or body.
2. Only new findings → new issue: title with package and CVE/id; body: version, manifest path, severity, advisory link if present in JSON, recommended upgrade if Snyk suggests. Labels: source:security-officer, audit:auto, plus Bug or team security label if that is your convention.
3. If the report is missing, empty, or Snyk did not run — do not invent vulnerabilities; you may create no issues. Do not generate fake JSON.
4. Do not create duplicates for a “daily report”: if there are no new CVEs — silence in Linear.

End of comment (if you wrote one): [GitHub SDLC daily-audit:security-officer]

YAML files differ by intent. This section names the patterns—the why—so you can choose your own filenames without copying ours by accident.

Concrete filenames for the reference org: Workflows catalog.

Intent: cron ticks for ordered SDLC roles on the delivery lane. Each tick: pick (deterministic) → maybe launch agent.

Invariants: one delivery role per time slot; pick runs before expensive steps; “no ticket qualified” exits zero—green, quiet.

Intent: cadence that does not starve the delivery queue. Writes to audit projects with evidence rules.

Invariants: audit jobs do not pick from the same Todo column as delivery unless you want stand-up to catch fire; new tickets cite artifacts.

Intent: CI / pipeline diagnostics; optional agent follow-up on a dedicated ticket or thread.

Invariants: platform health, not “ship features faster”; no silent product edits outside normal review.

Intent: extra automation on another cadence.

Invariants: not a replacement for the delivery grid; explicit guards and stop conditions.

Intent: human-opened PR path—previews, smoke tests, policy checks.

Why it matters: humans and bots share one repo; preview workflows keep human lanes fast without borrowing delivery cron.

Intent: Playwright (or similar) against a live dev/stage URL.

Why hosted matters: auth, CDN, third-party behaviour—localhost will not see them.

Intent: promote images or assets toward production—often manual or policy-gated.

Invariants: promotion stays human-owned unless automated with the same rigour as pick/launch; rollback story exists before you brag about velocity.

Intent: optional glue—events, notifications, bridging.

Invariants: webhooks should not become an undocumented second scheduler; idempotency matters.