proposal.md

Why brownfield work starts with a proposal

The failure mode of AI on an existing codebase is confident fiction: modules that do not exist, a dependency that was replaced last year, an API "improvement" that breaks three callers. The proposal forces the model to read first and to write down, with file references, what it found - so the requirements delta and the tasks that follow are anchored in the real repository, and a reviewer can check them against it.

The hard rule: read real files first

Both brownfield workflows refuse to advance past their entry stage until a local-workspace tool has actually returned file contents. The agent prefers packing the whole repository once (local_pack_codebase) and then grepping and reading specific files as your answers point at new areas. You provide the code one of two ways:

# The interview / explore stage will not advance until real files were read:
npx -y @myspec/mcp-server login            # once
npx -y @myspec/mcp-server reverse --root .  # from your project root, keep it running
# …or click "Mount folder" in the chat's Local Workspace panel (Chrome / Edge)

Nothing outside the granted root is reachable, access is read-only, and secret files are excluded. Details on the MCP server page.

The MySpec proposal

Written by the MySpec brownfield workflow to specs/<change>/proposal.md (the bundle name is a kebab-case verb phrase such as add-oauth-login). Four sections, in order; the title distinguishes a wide-scope Change Proposal from a single-module Change Request.

# Change Proposal: [Project Name]
<!-- or "# Change Request:" for a small change isolated in one module -->

## Why
2–5 sentences: the problem, the current behaviour, the modules / files involved.
Brownfield: describe what is changing and why now - not a greenfield build.

## What Changes
- One observable change per bullet (new behaviour, modified behaviour, removals)

## Technical Solution
### Library/Framework Changes        new dependency, bump, or replacement - and why
### Core Flow Changes                Mermaid sequence / flow: before → after
### Data Model / DB Schema Changes   Mermaid erDiagram of the affected entities
### API Breaking Changes             or "No breaking API changes."

## Impact
Affected code, data, APIs, users, migrations; backward-incompatible changes; risks.

• Technical Solution is the engineering core: a subsection is omitted only with an explicit "No library changes." - never silently.
• Two diagrams are expected - a Mermaid sequence or flow diagram for the changed core flow, and an erDiagram for schema changes.
• Not in this file: the full requirement text (that is the requirements delta) or a task breakdown.

The OpenSpec proposal

Written by the OpenSpec workflow to openspec/changes/<change-id>/proposal.md. Instead of a technical solution it names the capabilities the change touches - and that list is a contract: the specs stage must write exactly one delta spec.md per capability, no more, no fewer.

# Add session rename

## Why
Users cannot rename a chat session after the AI titles it; the summary lives in
context.sessionSummary (platform/internal/modules/project/domain/session.go) and only
the agent writes it.

## What Changes
- A rename action on the session list and chat header
- PATCH /project/v1/sessions/:id accepts { sessionSummary } (≤ 500 chars)

## Capabilities
### Modified Capabilities
- `webapp`: session list menu and chat header gain a rename dialog
- `platform`: session service validates and persists a user-supplied summary

## Impact
No schema change; realtime clients receive session.renamed; no breaking API changes.

Authoring and review rules

What the proposal unlocks

• MySpec: a Requirements Delta grouped by the same module names, then an optional tasks.md traced to its AR-/BR-/CR- codes.
• OpenSpec: one delta spec.md per capability, an optional design.md, and a tasks.md with one group per capability - all under the change folder the OpenSpec CLI reads.
• Either way: the proposal is the document to share with the team for sign-off before the delta is written - a public share link or the MCP server's read_spec_file puts it in front of them.