Oliverspec propose

Propose a change into Linear only. Never write OpenSpec folders, openspec/changes/, or other proposal markdown into the repository.

Artifacts created:

• Linear Project (create or reuse)
• Linear Document — PRD written from a product perspective (who/why/what experience)
• Linear Document — TRD written from a deeply technical perspective (how/where/with what systems)

Do not create Linear issues/tickets in this skill. Scoping into tickets is oliverspec-scope.

When PRD + TRD are ready: run oliverspec-scope, then oliverspec-apply.

---

Document voices (strict)

Doc	Voice	Audience	Contains	Does not contain
PRD	Product	PMs, design, eng reading for intent	Problem, users, jobs-to-be-done, UX/behavior, success metrics, product risks	Schemas, API shapes, class/file names, infra, algorithms
TRD	Deeply technical	Engineers implementing	Architecture, data model, APIs, codepaths, failure modes, migrations, rollout	Soft product copy, marketing framing, vague “make it better” goals without mechanism

If a sentence could only matter to an engineer implementing the change, it belongs in the TRD. If it could be read by product/design to judge whether we built the right thing, it belongs in the PRD.

Defaults

Setting	Default
Linear team	Engineering (override only if user specifies another team)
Persistence	Linear only — no repo writes for proposals
PRD	Linear Document on the project via save_document
TRD	Linear Document on the project via save_document

---

Input

Need from conversation or user:

1. What to build — problem, approach, scope (from explore or the request)
2. Project name — Linear project to create or reuse (ask if missing)

Optional: team override (default Engineering), priority, initiative.

IMPORTANT: Do not proceed without understanding what to build.

---

Steps

1. Crystallize the proposal (in chat first)

Before calling Linear, draft and show the user:

1. PRD outline (product voice — see template below)
2. TRD outline (deeply technical voice — see template below) — detailed enough to implement from without re-deriving design
3. Mermaid diagrams — product flows may appear lightly in the PRD; architecture / data / sequence diagrams belong in the TRD (never ASCII)

Ask the user to confirm before creating or updating anything in Linear.

Do not draft a ticket list here — that belongs to oliverspec-scope after the docs exist.

2. Resolve Linear project + team

1. Read Linear MCP tool schemas before calling tools
2. Default team: Engineering unless user specified otherwise
3. list_projects with the project name query
   • If a clear match exists → reuse it (confirm with user if ambiguous)
   • If none → save_project with name, setTeams: ["Engineering"] (or override), and a short summary
4. Note the project name/id for subsequent calls

3. Create or update the PRD document

Use save_document with project set to the Linear project.

• If a PRD doc already exists for this project (list_documents), update it by id
• Otherwise create: title like PRD: <feature name>

Write the PRD only from a product perspective: problem, users, outcomes, and observable product behavior. No implementation detail.

PRD template

# PRD: <Feature Name>

## Problem
<What hurts today, who feels it, and why it matters now>

## Goals
- <User/business outcomes — not engineering tasks>

## Non-goals
- <Explicit product boundaries>

## Users & use cases
- <Personas / roles and the jobs they need to complete>

## Product behavior
<End-to-end experience: happy path, edge cases, empty/error states — described as the user sees them>

## UX / interaction notes
<Screens, flows, copy intent, permissions as product rules — not component trees>

## Success metrics
- <How we know this worked for users/business>

## Risks & open questions
- <Product risks, unresolved product decisions>

## References
- TRD: <title / link filled after create>

PRD anti-patterns: tables of DB columns, endpoint lists, library choices, “we’ll use Redis”, file paths, Temporal workflow names. Those go in the TRD.

4. Create or update the TRD document

Use save_document with project set to the same Linear project.

• If a TRD doc already exists (list_documents), update it by id
• Otherwise create: title like TRD: <feature name>

Write the TRD from a deeply technical perspective. Assume the reader is an engineer who will implement and review the change. Be concrete: services, stores, schemas, APIs, control flow, failure modes. An implementer (or oliverspec-scope / oliverspec-apply) should not need to re-derive the design.

TRD template

# TRD: <Feature Name>

## Overview
<Technical summary — how we will build what the PRD requires>

## Current state
<Relevant systems, schemas, codepaths, ownership boundaries today — cite packages/services>

## Proposed architecture
<Components, boundaries, responsibilities, trust boundaries>
<!-- Mermaid: system / sequence / state diagrams -->

## Data model
<Schemas, migrations, stores (Postgres / ClickHouse / etc.), indexes, backwards compatibility, backfills>

## APIs & interfaces
<Routes, events, contracts, authz, idempotency, versioning>

## Detailed design
<Step-by-step control flow, algorithms, state transitions, concurrency, failure/retry modes>

## Integration points
<Existing services, workers, queues, third parties, config/env>

## Observability & ops
<Logging, metrics, tracing, alerts, feature flags, rollout / migrate / rollback>

## Testing strategy
<Unit / integration / e2e expectations tied to concrete modules>

## Risks, tradeoffs & alternatives considered
- <Technical tradeoffs with rationale>

## Open technical questions
- ...

## References
- PRD: <title / link>

TRD anti-patterns: restating the PRD in engineer voice without mechanisms; “make it scalable” without a design; product roadmap language. Cross-link PRD ↔ TRD in both documents after create (update with URLs/titles).

5. Done — hand off

Summarize:

• Project name + URL
• PRD document title + URL
• TRD document title + URL
• Prompt: "Run oliverspec-scope to break the PRD/TRD into Linear tickets, then oliverspec-apply to implement."

---

Guardrails

• No git/repo proposal artifacts — Linear only
• No tickets in propose — PRD + TRD documents only; oliverspec-scope owns issue creation
• Confirm plan before creating Linear objects
• Default team Engineering
• Diagrams in Mermaid only — architecture / flow sketches use Mermaid, not ASCII
• PRD = product voice — who/why/what experience; no implementation detail
• TRD = deeply technical voice — how/where/with what systems; concrete enough to implement
• TRD must not be a thin restatement of the PRD
• Prefer updating an existing project/PRD/TRD over duplicating when the user is iterating
• Read Linear tool descriptors before first MCP call in the session
• Do not start implementation or ticket slicing in this skill