rsc-universal 0.1.1

package/skills/prompt-engineering/references/output-contracts.md

@@ -0,0 +1,120 @@
+# Output contracts: per-provider strict recipes
+
+Pick the strongest mechanism the provider gives you. Provider APIs and version notes
+below verified 2026-06-02 (access date); each external figure carries its own source
+date inline — do not read the access banner as the date a cited number was published.
+
+## OpenAI — strict `json_schema` via `response_format`
+
+Highest reliability: the provider compiles the schema into a token-masking FSM, so the
+output is guaranteed to parse against the schema (**<0.1% schema-failure rate** — figure
+published by OpenAI at the Aug 2024 Structured Outputs launch, not a 2026 number). Set
+`strict: true` and mark every field required (use unions/nullable for optional).
+
+```python
+from openai import OpenAI
+from pydantic import BaseModel
+
+class Triage(BaseModel):
+    category: str  # "bug" | "billing" | "other"
+
+client = OpenAI()
+resp = client.chat.completions.parse(
+    model="gpt-…",                       # resolve the model id from config, not here
+    messages=[{"role": "user", "content": prompt}],
+    response_format=Triage,              # SDK emits strict json_schema under the hood
+)
+result = resp.choices[0].message.parsed  # already a Triage, or None on refusal
+```
+
+Raw form (no SDK helper):
+
+```json
+{
+  "type": "json_schema",
+  "json_schema": {
+    "name": "triage",
+    "strict": true,
+    "schema": {
+      "type": "object",
+      "properties": { "category": { "type": "string", "enum": ["bug", "billing", "other"] } },
+      "required": ["category"],
+      "additionalProperties": false
+    }
+  }
+}
+```
+
+## Anthropic — strict tool use
+
+Reliable schema adherence, close behind OpenAI strict. Define a single tool whose
+`input_schema` is your contract and force it. **Assistant-prefill structured output is
+dead in the latest models** — Anthropic's migration guide states prefill returns a `400`
+on Sonnet 4.6 / Opus 4.6 / Opus 4.7 and routes you to structured outputs / `output_config.format`
+(platform.claude.com/docs/en/about-claude/models/migration-guide). Do not use prefill to
+coerce a shape.
+
+```python
+import anthropic
+client = anthropic.Anthropic()
+msg = client.messages.create(
+    model="claude-…",                    # from config
+    max_tokens=256,
+    tools=[{
+        "name": "emit_triage",
+        "description": "Return the ticket category.",
+        "input_schema": {
+            "type": "object",
+            "properties": {"category": {"type": "string", "enum": ["bug", "billing", "other"]}},
+            "required": ["category"],
+        },
+    }],
+    tool_choice={"type": "tool", "name": "emit_triage"},
+    messages=[{"role": "user", "content": prompt}],
+)
+block = next(b for b in msg.content if b.type == "tool_use")
+result = block.input  # {"category": "..."}
+```
+
+**Streaming caveat:** Anthropic tool-use output arrives as ONE block at end of stream —
+you cannot read fields progressively. OpenAI/Gemini stream field-by-field. If your UI
+parses-as-it-streams, that path does not exist on Claude tool use.
+
+## Google Gemini — `responseSchema`
+
+Set `response_mime_type: "application/json"` and a `response_schema`. Validate after,
+same as any JSON path.
+
+```json
+{ "generationConfig": { "response_mime_type": "application/json", "response_schema": { "type": "OBJECT", "properties": { "category": { "type": "STRING", "enum": ["bug","billing","other"] } } } } }
+```
+
+## TypeScript schema surface (zod)
+
+```typescript
+import { z } from "zod";
+const Triage = z.object({ category: z.enum(["bug", "billing", "other"]) });
+// OpenAI: zodResponseFormat(Triage, "triage"); Anthropic: zodToJsonSchema(Triage) as input_schema.
+const parsed = Triage.parse(JSON.parse(raw));   // throws -> trigger retry
+```
+
+## Retry-on-parse-fail (for JSON mode / freeform only)
+
+Strict mechanisms above rarely need this. When you only have JSON mode or freeform,
+bound the retries and feed the parser error back:
+
+```python
+def call_with_retry(prompt, schema, parse, max_tries=2):
+    last_err = None
+    for _ in range(max_tries + 1):
+        raw = call_model(prompt if last_err is None
+                         else f"{prompt}\n\nYour previous output failed: {last_err}. Return only valid output.")
+        try:
+            return parse(raw, schema)          # raises on invalid
+        except Exception as e:
+            last_err = str(e)
+    raise ValueError(f"contract not met after retries: {last_err}")
+```
+
+Keep `max_tries` small (1-2). If a strict mechanism is available, use it instead of
+spending tokens on retries.

package/skills/prompt-engineering/scripts/verify.sh

@@ -0,0 +1,84 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Lints prompt artifacts in a target dir (default: cwd) against this skill.
+# Read-only: greps only, never writes, never installs, no network.
+# Scope: *.prompt, *.prompt.md, *.prompt.txt, prompts/**, and *.md/*.txt that
+#   contain a prompt marker (a "Role:"/"Task:" block or a fenced ```prompt).
+# Exit 0 = clean OR no prompt artifacts found (empty target is not a failure).
+# Exit 1 = a banned vague hedge was found in prompt text.
+# WARN (still exit 0) = JSON requested with no schema/contract nearby.
+
+TARGET="${1:-.}"
+if [ -t 1 ] && command -v tput >/dev/null 2>&1 && [ "$(tput colors 2>/dev/null || echo 0)" -ge 8 ]; then
+  YELLOW="$(tput setaf 3)"; RED="$(tput setaf 1)"; GREEN="$(tput setaf 2)"; RESET="$(tput sgr0)"
+else
+  YELLOW=""; RED=""; GREEN=""; RESET=""
+fi
+rc=0
+warn() { printf '%s[WARN]%s %s\n' "$YELLOW" "$RESET" "$1" >&2; }
+info() { printf '[INFO] %s\n' "$1"; }
+fail() { printf '%s[FAIL]%s %s\n' "$RED" "$RESET" "$1" >&2; rc=1; }
+
+if [ ! -e "$TARGET" ]; then
+  warn "target '$TARGET' does not exist; nothing to lint"
+  exit 0
+fi
+
+PRUNE='-path */node_modules/* -o -path */.venv/* -o -path */venv/* -o -path */.git/* -o -path */dist/* -o -path */build/*'
+
+# Collect candidate prompt files (newline-delimited; bash 3.2 safe, no mapfile).
+candidates=""
+add() { [ -n "$1" ] && candidates="${candidates}$1
+"; return 0; }
+while IFS= read -r f; do add "$f"; done <<EOF
+$(find "$TARGET" \( $PRUNE \) -prune -o -type f \
+   \( -name '*.prompt' -o -name '*.prompt.md' -o -name '*.prompt.txt' \) -print 2>/dev/null || true)
+EOF
+# Promote .md/.txt that carry an explicit ```prompt fence. Skill docs (SKILL.md and
+# files under references/) describe prompts and quote banned phrases on purpose, so they
+# are NOT prompt artifacts and must not be linted as such.
+while IFS= read -r f; do
+  [ -z "$f" ] && continue
+  case "$f" in */SKILL.md|*/references/*) continue ;; esac
+  if grep -qE '```[[:space:]]*prompt' "$f" 2>/dev/null; then add "$f"; fi
+done <<EOF
+$(find "$TARGET" \( $PRUNE \) -prune -o -type f \( -name '*.md' -o -name '*.txt' \) -print 2>/dev/null || true)
+EOF
+
+# De-dup.
+files="$(printf '%s' "$candidates" | awk 'NF && !seen[$0]++')"
+if [ -z "$files" ]; then
+  info "no prompt artifacts found under '$TARGET'; nothing to lint (ok)"
+  exit 0
+fi
+
+# Eval-set presence: a written prompt should ship with cases somewhere in the target.
+if find "$TARGET" \( $PRUNE \) -prune -o -type f -name 'cases.y*ml' -print 2>/dev/null | grep -q . \
+   || grep -rqsE '^[[:space:]]*should_trigger:|^[[:space:]]*cases:' "$TARGET" 2>/dev/null; then
+  info "eval cases present near the prompt(s)"
+else
+  warn "prompt artifacts found but no eval cases (cases.yaml or 'cases:'/'should_trigger:') — write a small set before tuning"
+fi
+
+# Banned vague hedges in prompt text -> hard fail.
+BANNED='try to|please attempt|if possible|as best you can|do your best'
+while IFS= read -r f; do
+  [ -z "$f" ] && continue
+  if grep -niE "$BANNED" "$f" >/dev/null 2>&1; then
+    fail "vague hedge in prompt text: $f"
+    grep -niE "$BANNED" "$f" | sed 's/^/    /' >&2
+  fi
+  # JSON requested but no schema/contract signal nearby -> warn only.
+  if grep -qiE 'json' "$f" 2>/dev/null \
+     && ! grep -qiE 'schema|strict|response_format|json_schema|tool[_ ]?use|responseSchema' "$f" 2>/dev/null; then
+    warn "JSON requested with no schema/contract signal in $f (JSON mode guarantees valid JSON, not your schema)"
+  fi
+done <<EOF
+$files
+EOF
+
+if [ "$rc" -eq 0 ]; then
+  printf '%s[OK]%s prompt lint passed\n' "$GREEN" "$RESET"
+fi
+exit "$rc"

package/skills/proposals/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: proposals
+description: "Use when writing the document a buyer reads to say yes — a commercial proposal or Statement of Work (SOW), turning discovery notes into a scoped priced doc, adding Good/Better/Best tiers, or fixing a proposal that won't close. Triggers: 'write a proposal for this client', 'draft a SOW / scope of work', 'turn this discovery call into a proposal', 'add pricing tiers so the middle one wins', 'why isn't this proposal closing', 'scope this so the client can't keep adding free work', 'propuesta comercial / propuesta de servicios', 'proposta comercial / abast del projecte'. NOT the binding legal agreement, MSA, liability/IP clauses (that is contracts), NOT deciding what number to charge or the margin (that is pricing), NOT the slide deck that pitches the vision to a room (that is pitch-deck)."
+tags: [proposals, sow, sales, scope]
+recommends: [contracts, pricing, invoicing, sales-pipeline, pitch-deck, brand-voice]
+origin: risco
+---
+
+# proposals
+
+You write the artifact that converts a discovered need into a yes: the commercial **proposal** and the **Statement of Work (SOW)**. Your job is persuasion *plus* scope *plus* terms — anchored on the buyer's problem in their own words, with explicit inclusions and exclusions, tiered pricing, deliverables that pass or fail against acceptance criteria, milestones, payment terms, and one concrete next step.
+
+You are a close-oriented commercial writer. You consume the price model and hand off binding terms. You do not draft enforceable legal clauses and you do not decide the numbers.
+
+Median proposal-to-close is **25%**; top quartile is **35%+** (study of 939 companies, 23,000 opportunities, Optifai 2026-04-20). That is the bar. Most of the lift below is the gap between those two numbers — and it is structural, not prose polish.
+
+## Two artifacts, one job
+
+| Artifact | What it is | Write it when |
+|---|---|---|
+| **Proposal** | The persuasive, scoped, priced document the buyer reads to commit. Exec summary → problem → solution → scope → tiers → timeline → proof → terms → next step. | The buyer needs to be convinced and to choose. Default deliverable. |
+| **SOW** | The scoped/termed annex: inclusions, **exclusions**, deliverables with acceptance criteria, milestones, change-order clause, payment schedule. Usually a child of an MSA. | Scope must be contractually precise — once they've said "yes, in principle," or the engagement runs under an existing MSA. |
+
+A proposal persuades and frames; a SOW pins down. Often you write both: the proposal sells, the SOW (or its scope section) becomes the annex that legal attaches under the MSA.
+
+## Route out — do not write the wrong document
+
+| The ask | Goes to | Because |
+|---|---|---|
+| MSA, liability/indemnity, IP assignment, governing law, signature-for-enforceability | `../contracts/SKILL.md` | Binding legal terms — the moment language is enforceable, it is not yours. |
+| "What should we charge? What's the margin / package?" | `../pricing/SKILL.md` | Deciding the number and the model, not presenting it. |
+| Slide deck to pitch the vision to a room or board | `../pitch-deck/SKILL.md` | Visual narrative, not a scoped/termed document. |
+| Send it, chase it, move the stage, follow-up cadence | `../sales-pipeline/SKILL.md` | Tracking and CRM, not authoring. |
+| Deal won — bill it, collect payment | `invoicing` | Billing after the win. |
+| Cold first-touch to get the meeting | `../cold-outreach/SKILL.md` | First contact, no scope to propose yet. |
+| Tone, naming, voice rules for the copy | `../brand-voice/SKILL.md` | You pull voice from there; you don't define it. |
+
+The one-sentence boundary: a proposal is the persuasive scoped priced document that gets a buyer to commit; the moment the language becomes binding legal terms it belongs to `contracts`, and the moment the question is "what number / what model" rather than "how do I present and scope it," it belongs to `pricing`.
+
+## Intake gate — STOP if you can't fill these
+
+You cannot write a proposal that closes from a feature list. Before drafting, you must have:
+
+1. **The buyer's problem in their own words** — the literal phrasing from the call or brief.
+2. **The success metric** — how they'll know it worked (a number, a date, a state).
+3. **A budget signal** — band, anchor, or stated constraint. Needed to pitch tiers.
+4. **The decision process** — who signs, who influences, what timeline.
+5. **Why now** — the trigger that makes this urgent.
+
+Rule: **if you cannot personalize the executive summary to this buyer, do not write it yet — interview first.** Customized exec summaries close at **34% vs 17%** generic; when ~30% of the summary is tailored per client, close rates rise ~50% (Optifai 2026-04-20; DocSend via Thornton & Lowe 2026-06-02). A generic summary literally halves your odds. If you only have a feature list, say so and ask the five questions.
+
+Pull tone and naming from `../brand-voice/SKILL.md` before writing prose.
+
+## Proposal anatomy
+
+Write these sections in this order. Each earns its place.
+
+1. **Cover / title** — client name, project name, date, validity window. Personalization starts on the cover.
+2. **Executive summary** (200–400 words) — the one section most buyers actually read. Structure: *their challenge → your solution → the outcome → the investment.* At least ~30% must be specific to this buyer (their words, their metric, their constraint). No solution-features here — outcomes.
+3. **Problem framing** — restate their problem and its cost in their terms. Earns the right to propose.
+4. **Proposed solution** — your approach, mapped to the problem. What changes for them.
+5. **Scope summary** — what's in, with a one-line nod to what's out (full exclusions live in the SOW).
+6. **Pricing tiers** — Good/Better/Best (next section).
+7. **Timeline / milestones** — phases with dates, so effort feels concrete.
+8. **Proof / qualifications** — one or two relevant results, not a logo wall.
+9. **Terms summary** — payment schedule, validity, what happens next. Binding clauses are referenced, not drafted here.
+10. **Next step** — the close (see "The close").
+
+Full template and a filled mini-example: `references/proposal-skeleton.md`.
+
+## Tiered pricing — present three, recommend the middle
+
+Single-price quotes leave money and close rate on the table. Three-tier pricing lifts close rate **~23%** vs a single price; the middle tier wins **~66%** of the time, and the high tier exists to anchor (Optifai 2026-04-20; Freshproposals/INSEAD 2026-06-02). Decide the actual numbers in `../pricing/SKILL.md` — here you present them.
+
+Rules:
+- **Name tiers by outcome, not by feature count.** "Launch / Scale / Dominate" beats "Tier 1 / Tier 2 / Tier 3."
+- **Mark the middle as recommended.** Make it the obvious choice; it should map to what most buyers actually need.
+- **The top tier anchors** — it should be visibly more, so the middle looks reasonable.
+- **Each tier states its outcome**, not just its inclusions.
+
+```text
+Bad  (single price, feature-framed)
+  Website redesign — $24,000. Includes 8 pages, CMS, SEO setup, 2 revisions.
+
+Good (three tiers, outcome-framed, middle recommended)
+  Launch   $18k  — Get the new site live: 8 pages, CMS, handoff.
+  Scale    $28k  ★ recommended — Live + ranking + converting: + SEO, analytics, 90-day tuning.
+  Dominate $46k  — Scale + a measurable pipeline: + landing-page system, A/B program, quarterly review.
+```
+
+## SOW anatomy
+
+The SOW is where vague proposals go to fail. Over **78%** of project failures trace to unclear requirements (ITToolKit/Atlassian 2026-06-02). Every section below is load-bearing. Full template: `references/sow-skeleton.md`.
+
+1. **Scope — inclusions.** Numbered, specific, quantified.
+2. **Scope — explicit EXCLUSIONS.** The single most important section. The expensive failure mode is the client assuming a task is in scope while you assumed it was out. State what you are *not* doing. If it's not listed in inclusions, name it here.
+3. **Deliverables with acceptance criteria** — a table. Each criterion must be specific enough that a **third party can judge pass/fail** without asking you. "Looks good" is not a criterion; "loads in <2s on 4G, passes the 6 checks in Appendix A" is.
+4. **Milestones and dates** — phased, dated, each tied to a deliverable.
+5. **Change-order clause** — mandatory. Every scope/timeline/budget change requires *written approval* via a formal change order with updated deliverables, cost, and dates. This is your primary scope-creep defense (Malbek/Icertis 2026-06-02).
+6. **Payment schedule** — tied to milestones, not the calendar. Deposit → milestone payments → final on acceptance.
+7. **MSA reference** — the SOW is the child; the MSA is the parent governing legal/payment/IP/dispute terms (Sirion/Ironclad 2026-06-02). Reference it; do not re-litigate its clauses. That referencing is exactly why binding terms route to `../contracts/SKILL.md`.
+
+### Deliverable table shape
+
+```markdown
+| # | Deliverable        | Acceptance criteria (third-party testable)                  | Due     |
+|---|--------------------|-------------------------------------------------------------|---------|
+| 1 | Data migration     | 100% of 12,400 records migrated; row counts match source;   | Week 4  |
+|   |                    | 0 records in error queue; client signs off on 20-row sample |         |
+| 2 | Cutover runbook    | Reproduced by a client engineer with no author present      | Week 6  |
+```
+
+## Scope-creep defense — kill weasel words
+
+Every vague noun is a future free-work argument. Replace each with a quantity, a number, or a bound.
+
+| Bad (vague, unbounded) | Good (bounded, testable) |
+|---|---|
+| "...and ongoing support, etc." | "30 days post-launch support: up to 10 hrs, email, <1 business-day response." |
+| "Revisions as needed." | "Two rounds of revisions per deliverable; further rounds via change order at $X/hr." |
+| "SEO optimization and more." | "On-page SEO for the 8 listed pages: titles, meta, headings, schema. Off-page is out." |
+| "Content to be provided." | "Client provides final copy for all pages by Week 2; delay shifts the timeline 1:1." |
+| "Scope: TBD." | Never ship a TBD in scope. Resolve it or move it to exclusions. |
+
+If a word doesn't survive the question "could two reasonable people read this differently?", rewrite it.
+
+## The close — a next step, never "let me know"
+
+Proposals that end with a timeline of specific next steps close **~28%** more; pre-handling objections lifts win rate **~19%**; no follow-up within 7 days closes **40%** less (Optifai 2026-04-20). So:
+
+- **Mutual action plan**: 2–4 dated next steps for *both* sides (e.g. "Mon: you confirm tier; Tue: we send the SOW; Wed: kickoff"). Not "let me know your thoughts."
+- **Pre-handle 1–2 objections** the buyer is likely to raise (price vs scope, timing, risk) before they have to ask.
+- **Validity window** — "this pricing holds through [date]" — gives a reason to decide.
+- **One CTA**, concrete and singular: sign the tier, book the kickoff, return the SOW. Not three soft options.
+
+Sending and chasing the proposal afterward is `../sales-pipeline/SKILL.md`.
+
+## Anti-patterns
+
+| Anti-pattern | Why it loses | Do instead |
+|---|---|---|
+| Exec summary that lists your features | Buyer reads it first and sees you, not them; generic summaries close at half the rate | Their challenge → your solution → outcome → investment, ~30% tailored |
+| Single price | Leaves ~23% close rate on the table; no anchor, no choice | Three outcome-named tiers, middle recommended |
+| Scope with inclusions but no exclusions | The #1 scope-creep entry point; both sides assume differently | Explicit EXCLUSIONS section naming what you won't do |
+| "Deliver a great website" (unmeasurable) | No way to judge done; final payment stalls | Acceptance criteria a third party can pass/fail |
+| No change-order clause | Every "small extra" is a free-work fight | Written-approval change order with updated cost/date |
+| Liability / IP / governing-law clauses written into the proposal | You're drafting unenforceable or risky legal terms | Reference the MSA; route binding terms to `../contracts/SKILL.md` |
+| Closing with "let me know your thoughts" | No decision forcing function; the deal drifts | Dated mutual action plan + one concrete CTA + validity window |
+| Price with no value framing | Buyer compares on cost alone | Tie every tier to its outcome before the number |
+
+## Verify and hand off
+
+- Run `scripts/verify.sh <path-to-proposal-or-sow.md>` on your draft. It greps for the required sections, flags weasel words (`etc.`, `as needed`, `and more`, `TBD`, unbounded `ongoing`), warns on smuggled binding-legal language, and sanity-checks exec-summary length. It is a structural lint, not a quality judge — passing it means the contract of sections is intact, not that the prose persuades.
+- Hand binding terms to `../contracts/SKILL.md`, the numbers/model to `../pricing/SKILL.md`, post-win billing to `invoicing`, and send/track to `../sales-pipeline/SKILL.md`.
+
+## References
+
+- `references/proposal-skeleton.md` — full ordered proposal template + a filled one-page services example.
+- `references/sow-skeleton.md` — full SOW template: scope/exclusions, deliverable+acceptance-criteria table, change-order clause text, milestone payment schedule, MSA-annex note.

package/skills/proposals/evals/README.md

@@ -0,0 +1,3 @@
+# Evals — proposals
+
+`cases.yaml` holds three things: `should_trigger` (prompts that must route into this skill, including a non-obvious "why isn't this closing" diagnostic and Spanish/Catalan phrasings), `should_not_trigger` (prompts that belong to a named sibling — `contracts`, `pricing`, `pitch-deck`, `invoicing`, `sales-pipeline`, `cold-outreach`), and one `capability` scenario with a `must_include` rubric. There is no automated runner here: route the trigger prompts through your skill-selection harness and confirm each lands (or doesn't) as labelled, then have an agent run the capability scenario and score the output against the rubric by hand — every `must_include` line should be present and pass. To sanity-check a generated proposal/SOW structurally, run `../scripts/verify.sh <draft.md>`; a clean rubric pass plus a clean verify run is the bar.

package/skills/proposals/evals/cases.yaml

@@ -0,0 +1,53 @@
+skill: proposals
+
+should_trigger:
+  - prompt: "Write a commercial proposal for the Acme website redesign."
+    why: Core job — the persuasive, scoped, priced document a buyer reads to commit.
+  - prompt: "Draft a statement of work for the 8-week data-migration engagement."
+    why: The SOW is this skill's second artifact (scope, exclusions, acceptance criteria, terms).
+  - prompt: "Add Good/Better/Best tiers to this offer so the middle one wins."
+    why: Tiered presentation and anchoring — the three-tier pattern that lifts close rate ~23%.
+  - prompt: "Esta propuesta no cierra, ¿por qué? Haz que cierre."
+    why: Non-obvious + Spanish — diagnosing a non-closing proposal is a proposals job (exec summary, tiers, close), not pipeline tracking.
+  - prompt: "Scope this so the client can't keep adding work for free."
+    why: Non-obvious — the request is really for explicit exclusions + a change-order clause, the scope-creep defense.
+  - prompt: "Turn these discovery-call notes into a proposal."
+    why: Discovery-to-proposal is the canonical intake-to-artifact flow.
+  - prompt: "Necessito redactar l'abast del projecte i la proposta comercial per al client."
+    why: Catalan — SOW (abast) + commercial proposal, squarely this skill.
+
+should_not_trigger:
+  - prompt: "Draft the MSA and add liability and IP-assignment clauses."
+    route_to: contracts
+    why: Binding, enforceable legal terms — not the persuasive scoped doc.
+  - prompt: "What should we charge for this engagement and what's our margin?"
+    route_to: pricing
+    why: Deciding the number and the model, not presenting it in a proposal.
+  - prompt: "Build the slide deck to pitch this to their board."
+    route_to: pitch-deck
+    why: Visual narrative for a room, not a scoped/termed document.
+  - prompt: "The deal closed — send the invoice."
+    route_to: invoicing
+    why: Billing after the win, downstream of the proposal.
+  - prompt: "Set up follow-up reminders and move this deal to the negotiation stage."
+    route_to: sales-pipeline
+    why: Tracking and cadence, not authoring the document.
+  - prompt: "Write a cold email to get a first meeting with this prospect."
+    route_to: cold-outreach
+    why: First-touch messaging — there's no discovered need to scope yet.
+
+capability:
+  - scenario: >
+      Given short discovery notes — buyer problem ("support drowning in ~200
+      password/order-status tickets a week"), a rough budget band (~$30–60k), and a
+      6-week window — produce a complete proposal plus the SOW that annexes it.
+    must_include:
+      - Personalized executive summary structured problem -> solution -> outcome -> investment, using the buyer's own words, not a feature dump.
+      - Three outcome-named pricing tiers with the middle marked recommended.
+      - A scope section with an explicit EXCLUSIONS subsection naming what is out.
+      - Deliverables each with acceptance criteria a third party can judge pass/fail.
+      - A change-order clause requiring written approval with updated cost and dates.
+      - A payment schedule tied to milestones, not the calendar.
+      - A mutual-action-plan close with dated next steps, one concrete CTA, and a validity window.
+      - No weasel words (etc., as needed, and more, TBD, unbounded ongoing).
+      - No smuggled binding-legal clauses, with a note that those route to contracts and the MSA governs.

package/skills/proposals/references/proposal-skeleton.md

@@ -0,0 +1,110 @@
+# Proposal skeleton
+
+Full ordered template, then a filled one-page mini-example. Replace every `[...]`.
+Keep the section order — buyers read top-down and the exec summary carries the most weight.
+
+## Template
+
+```markdown
+# Proposal: [Project name]
+**Prepared for:** [Client name] · **By:** [Your company] · **Date:** [date]
+**Valid through:** [date — give them a reason to decide]
+
+## Executive summary
+[200–400 words. At least ~30% specific to this buyer. Structure:]
+- The challenge: [their problem, in their words, with its cost].
+- Our solution: [your approach in one paragraph — outcomes, not features].
+- The outcome: [the measurable change — their success metric].
+- The investment: [the band, pointing to the recommended tier below].
+
+## The problem
+[Restate their situation and what it costs them today. Earn the right to propose.]
+
+## Proposed solution
+[Your approach mapped to the problem. What changes for them, and how you'll get there.]
+
+## What's included (scope summary)
+[Numbered, specific. One line on what's out — full exclusions in the SOW.]
+
+## Investment
+[Three tiers, outcome-named, middle marked recommended. See the tier block below.]
+
+## Timeline
+[Phased with dates. Each phase ties to a deliverable.]
+
+## Why us
+[One or two relevant results with numbers. Not a logo wall.]
+
+## Terms
+- Payment: [schedule tied to milestones].
+- Validity: [date].
+- Governed by [MSA dated …] / binding terms to follow in the SOW + agreement.
+
+## Next steps
+[2–4 dated mutual actions + one concrete CTA. Pre-handle one likely objection.]
+```
+
+## Pricing tier block
+
+```markdown
+| Tier         | Outcome                                  | Investment |
+|--------------|------------------------------------------|------------|
+| Launch       | Get it live and handed off               | $[X]       |
+| Scale ★      | Live + measurably working (recommended)  | $[Y]       |
+| Dominate     | Scale + a compounding system             | $[Z]       |
+```
+
+The numbers come from `../../pricing/SKILL.md`. Here you only present and frame them.
+
+## Filled mini-example (services engagement)
+
+```markdown
+# Proposal: Customer portal rebuild
+**Prepared for:** Northwind Logistics · **By:** Atlas Studio · **Date:** 2026-06-02
+**Valid through:** 2026-06-20
+
+## Executive summary
+Northwind's support team told us the current portal generates "200+ password and
+order-status tickets a week" — roughly a third of all support volume — because
+customers can't self-serve. That ticket load is the problem we're solving, not the
+portal's looks. We propose to rebuild the portal around the four jobs your customers
+actually come to do: check order status, manage shipments, update billing, and reset
+access — each instrumented so you can watch ticket volume fall. The target you set on
+our call was "cut self-service tickets in half within one quarter." Our recommended
+Scale engagement is built to hit that and prove it with before/after dashboards. The
+investment for that path is $42,000, phased across a 6-week build.
+
+## The problem
+~200 self-service tickets/week, ~30% of support volume, each ~$14 fully loaded — about
+$145k/year of avoidable cost, plus the customer friction behind it.
+
+## Proposed solution
+Rebuild the four core flows, instrument each with event tracking, and ship a
+ticket-volume dashboard so the impact is visible, not asserted.
+
+## What's included (scope summary)
+1. Order-status, shipment, billing, and access-reset flows. 2. Analytics + dashboard.
+3. Two rounds of revisions per flow. Migration of legacy tickets is out (see SOW).
+
+## Investment
+| Tier      | Outcome                                         | Investment |
+|-----------|-------------------------------------------------|------------|
+| Launch    | New portal live, four flows shipped             | $28,000    |
+| Scale ★   | Live + instrumented + 90-day tuning (recommended)| $42,000   |
+| Dominate  | Scale + agent-deflection bot + quarterly review | $66,000    |
+
+## Timeline
+Wk 1 discovery & design · Wk 2–4 build · Wk 5 QA & instrumentation · Wk 6 launch.
+
+## Why us
+We cut self-service tickets 58% for a comparable 3PL in one quarter (case on request).
+
+## Terms
+Payment: 40% on signature, 30% at Wk 4 milestone, 30% on acceptance. Valid to 2026-06-20.
+Governed by the MSA dated 2026-01-15; scope detailed in the attached SOW.
+
+## Next steps
+1. 2026-06-09 — you confirm the Scale tier. 2. 2026-06-10 — we send the SOW for sign-off.
+3. 2026-06-16 — kickoff. On budget: the Scale tier pays for itself in ~3.5 months of
+deflected tickets. Reply to confirm the tier and we'll send the SOW the next morning.
+```

package/skills/proposals/references/sow-skeleton.md

@@ -0,0 +1,79 @@
+# SOW skeleton
+
+Full Statement of Work template. The SOW is the child of an MSA: it scopes one project,
+references the MSA for legal/payment/IP/dispute terms, and does not re-litigate them.
+The four load-bearing sections are **exclusions**, **acceptance criteria**,
+**change order**, and **payment schedule** — verify.sh fails a SOW missing any of them.
+
+## Template
+
+```markdown
+# Statement of Work — [Project name]
+**Client:** [name] · **Provider:** [name] · **Effective:** [date]
+**Governed by:** Master Services Agreement dated [date] ("the MSA"). This SOW is an
+annex under the MSA; the MSA's terms (liability, IP, governing law, dispute resolution)
+control and are not restated here.
+
+## 1. Scope — included
+1. [Specific, quantified work item.]
+2. [Specific, quantified work item.]
+3. [...]
+
+## 2. Scope — EXCLUDED (read this section to both sides on kickoff)
+The following are explicitly NOT part of this SOW and require a separate SOW or
+change order:
+- [Adjacent task the client might assume is included.]
+- [Maintenance / support beyond the window in §1.]
+- [Third-party costs, licenses, content the client must provide.]
+- Anything not listed in §1 is out of scope.
+
+## 3. Deliverables and acceptance criteria
+| # | Deliverable | Acceptance criteria (third-party testable) | Due |
+|---|-------------|--------------------------------------------|-----|
+| 1 | [name]      | [pass/fail an outsider can judge]          | Wk[x] |
+| 2 | [name]      | [pass/fail an outsider can judge]          | Wk[x] |
+Acceptance: client reviews within [N] business days; silence past [N] days = accepted.
+
+## 4. Milestones and timeline
+| Milestone | Deliverable(s) | Target date |
+|-----------|----------------|-------------|
+| Kickoff   | —              | [date]      |
+| [phase]   | #1             | [date]      |
+| Final     | #2, acceptance | [date]      |
+
+## 5. Change-order process
+Any change to scope, timeline, or budget requires a written change order signed by
+both parties before work begins. Each change order states the revised deliverables,
+the cost delta, and the new dates, and attaches to this SOW. Verbal requests and
+out-of-scope work in progress are not authorized and are not billable until a change
+order is signed.
+
+## 6. Payment schedule (tied to milestones, not the calendar)
+| Trigger                  | Amount   |
+|--------------------------|----------|
+| On signature             | [%]      |
+| On [milestone]           | [%]      |
+| On acceptance of #[last] | [%]      |
+Invoices issued per the MSA; collection and billing handled separately (invoicing).
+
+## 7. Assumptions and client responsibilities
+- [What the client must provide, by when; delay shifts the timeline 1:1.]
+- [Access, environments, decision-maker availability.]
+```
+
+## Change-order clause — drop-in text
+
+```text
+Change orders. Either party may request a change to scope, schedule, or fees. No
+requested change is in effect, and no out-of-scope work is billable, until both
+parties sign a written change order stating: (a) the revised or added deliverables,
+(b) the change in fees, and (c) the revised dates. Signed change orders attach to and
+amend this SOW; the MSA continues to govern all other terms.
+```
+
+## MSA-annex note
+
+Keep the SOW about *this project's scope and money*. Liability caps, indemnity, IP
+ownership/assignment, confidentiality, governing law, and signature-for-enforceability
+live in the MSA — route any of that to `../../contracts/SKILL.md`. If there is no MSA
+yet, flag it: the SOW should not carry the legal weight of one.