refactor(docs): migrate MVP specs to spec-driven structure

.cursor/rules/domain.md

@@ -14,11 +14,11 @@ How the engineering skills should consume this repo's domain documentation when
 ## Before exploring, read these
 
 - **`CONTEXT.md`** at the repo root (ubiquitous language; created or extended by `/grill-with-docs` when terms are resolved).
-- **`docs/adr/`** — architectural decision records for cross-cutting choices.
-- **`docs/mvp/architecture/architecture.md`** — MVP vision, closed decisions, and module map (canonical during spec-driven phase).
-- **Relevant `docs/mvp/features/<feature>.md`** — feature scope and acceptance criteria for the area you are changing.
+- **`spec/adr/`** — architectural decision records for cross-cutting choices.
+- **`spec/constitution/mission.md`** — MVP vision, closed decisions, and module map (canonical during spec-driven phase).
+- **Relevant `spec/features/00N-slug/spec.md`** — feature scope and acceptance criteria for the area you are changing.
 
-If `CONTEXT.md` or `docs/adr/` do not exist yet, **proceed silently**. Do not flag their absence or suggest creating them upfront. Use `docs/mvp/` as the source of truth until `/grill-with-docs` materializes terms into `CONTEXT.md`.
+If `CONTEXT.md` or `spec/adr/` do not exist yet, **proceed silently**. Do not flag their absence or suggest creating them upfront. Use `spec/` as the source of truth until `/grill-with-docs` materializes terms into `CONTEXT.md`.
 
 Do not treat `src/` or `notebooks/` as canonical architecture; they are legacy exploration per `AGENTS.md`.
 
@@ -27,24 +27,22 @@ Do not treat `src/` or `notebooks/` as canonical architecture; they are legacy e
 ```
 /
 ├── CONTEXT.md                 ← ubiquitous language (extend via grill-with-docs)
-├── docs/
-│   ├── adr/                   ← system-wide ADRs
-│   ├── agents/                ← agent skill config (this folder)
-│   └── mvp/
-│       ├── architecture/
-│       └── features/
+├── spec/
+│   ├── constitution/          ← mission, tech-stack, roadmap
+│   ├── features/              ← 00N-slug/spec.md (+ plan.md, tasks.md)
+│   └── adr/
 └── src/                       ← implementation (not planning truth)
 ```
 
 ## Use CONTEXT vocabulary
 
-When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), prefer terms from `CONTEXT.md` when defined there; otherwise use terms consistently with `docs/mvp/` (e.g. point-in-time, universe, EY rank, Magic Formula replica).
+When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), prefer terms from `CONTEXT.md` when defined there; otherwise use terms consistently with `spec/` (e.g. point-in-time, universe, EY rank, Magic Formula replica).
 
 If the concept you need isn't in `CONTEXT.md` yet, either reconsider invented language or note the gap for `/grill-with-docs`.
 
 ## Flag ADR conflicts
 
-If your output contradicts an existing ADR or a **closed decision** in `docs/mvp/architecture/architecture.md`, surface it explicitly rather than silently overriding:
+If your output contradicts an existing ADR or a **closed decision** in `spec/constitution/mission.md`, surface it explicitly rather than silently overriding:
 
 > _Contradicts [decision or ADR] — but worth reopening because…_
 

.cursor/rules/github-issues.mdc

@@ -0,0 +1,24 @@
+---
+description: GitHub Issues vs Git specs
+alwaysApply: true
+---
+
+# GitHub Issues workflow
+
+**Git specs in `spec/` are canonical.** GitHub Issues track execution.
+
+## Issue fields
+
+Each implementation issue should include:
+
+- **Title:** e.g. `Feature: Cheap Stocks — implement EY rank`
+- **Spec path:** `spec/features/00N-slug/spec.md`
+- **Body:** link to `plan.md` and `tasks.md` when they exist; copy acceptance criteria from the spec
+
+## Sync discipline
+
+1. Change MVP decisions in the Git spec first.
+2. Create or update the GitHub issue (label `ready-for-agent` when ready).
+3. On completion: update `spec.md` (implementation status, acceptance criteria), check off `tasks.md`, close the issue.
+
+See [`spec/meta/github-issues.md`](../../spec/meta/github-issues.md).

.cursor/rules/issue-tracker.md

@@ -18,15 +18,15 @@ Issues and PRDs for this repo live as GitHub issues. Use the `gh` CLI for all op
 
 Infer the repo from `git remote -v` — `gh` does this automatically when run inside a clone (`JLaborda/SmartWealthAI`).
 
-## Relationship to Git specs and Notion
+## Relationship to Git specs
 
 | Layer | Where | Role |
 | --- | --- | --- |
-| **MVP specs (canonical)** | `docs/mvp/features/*.md`, `docs/mvp/architecture/architecture.md` | Product and engineering truth; update before closing work |
-| **GitHub issues** | This repo's GitHub Issues | PRDs, vertical slices, and triage for Matt Pocock engineering skills (`to-issues`, `to-prd`, `triage`) |
-| **Notion tasks** | Board `Cursor Agent Tasks` | Optional execution tracking via Notion MCP; see `AGENTS.md` and `docs/mvp/NOTION_SETUP.md` |
+| **MVP specs (canonical)** | `spec/features/00N-slug/spec.md`, `spec/constitution/mission.md` | Product and engineering truth; update before closing work |
+| **GitHub issues** | This repo's GitHub Issues | Feature implementation tracking, PRDs, vertical slices, triage |
+| **`tasks.md`** | `spec/features/00N-slug/tasks.md` | Versioned checklist when a feature is in progress |
 
-When a skill publishes to the issue tracker, create or update a **GitHub issue**. Link the relevant `docs/mvp/features/...` path in the issue body. Do not treat Notion as the issue tracker for those skills unless the user explicitly asks to sync there.
+When a skill publishes to the issue tracker, create or update a **GitHub issue**. Link the relevant `spec/features/.../spec.md` path in the issue body. See [`spec/meta/github-issues.md`](../../spec/meta/github-issues.md).
 
 ## When a skill says "publish to the issue tracker"
 

.cursor/rules/mvp-docs.mdc

@@ -1,19 +1,20 @@
 ---
 description: MVP Markdown spec structure and editing conventions
-globs: docs/**
+globs: spec/**
 alwaysApply: false
 ---
 
 # MVP documentation conventions
 
-When creating or editing specs under `docs/mvp/`:
+When creating or editing specs under `spec/`:
 
 ## Feature specs
 
-Follow the structure used in existing features (e.g. `docs/mvp/features/cheap-stocks.md`):
+Follow the structure in [`spec/meta/feature-spec-template.md`](../../spec/meta/feature-spec-template.md) and existing features (e.g. `spec/features/003-cheap-stocks/spec.md`):
 
 - Objective
-- MVP scope / Out of MVP scope
+- Delivery (phase / roadmap link)
+- In scope / Out of scope
 - Inputs (tables where helpful)
 - Flow or logic (include at least one **Mermaid** diagram when the flow changes)
 - Acceptance criteria
@@ -23,7 +24,7 @@ Add **Implementation status** when coding starts: `planned` | `in_progress` | `d
 
 ## Architecture spec
 
-- Record closed decisions in tables (see "Decisions made so far" in `docs/mvp/architecture/architecture.md`).
+- Record closed decisions in tables (see "Decisions made so far" in `spec/constitution/mission.md`).
 - Cross-link feature files from the module table.
 - Do not contradict a closed architecture decision without updating the architecture doc first.
 

.cursor/rules/project-context.mdc

@@ -9,22 +9,22 @@ SmartWealthAI is a modular **quantitative value investing** system (MVP): US equ
 
 ## Current phase
 
-**MVP planning and spec refinement** in `docs/mvp/`. **June 30, 2026 demo slice** ([`demo-slice.md`](../../docs/mvp/demo-slice.md)) is the active delivery target. Prefer updating specs over writing code unless the user explicitly moves to implementation.
+**MVP planning and spec refinement** in `spec/`. **June 30, 2026 demo slice** ([`roadmap.md`](../../spec/constitution/roadmap.md)) is the active delivery target. Prefer updating specs over writing code unless the user explicitly moves to implementation.
 
 ## Canonical documentation
 
-- Demo slice: `docs/mvp/demo-slice.md`
-- ADRs: `docs/adr/`
-- Architecture: `docs/mvp/architecture/architecture.md`
-- Features: `docs/mvp/features/*.md`
+- Constitution: `spec/constitution/` (`mission.md`, `tech-stack.md`, `roadmap.md`)
+- ADRs: `spec/adr/`
+- Features: `spec/features/00N-slug/spec.md` (optional `plan.md`, `tasks.md`)
 - Ubiquitous language: `CONTEXT.md`
-- Requirements (historical): `docs/mvp/requirements/requirements.md`
-- Backlog: `docs/mvp/backlog/backlog.md`
+- Archive (historical): `spec/archive/requirements.md`
+- Backlog: `spec/backlog/backlog.md`
+- GitHub Issues workflow: `spec/meta/github-issues.md`
 
 ## Not canonical
 
 Do not use `src/` or `notebooks/` as reference architecture. Legacy exploration there does not define MVP boundaries.
 
 ## Code changes
 
-Every implementation change must trace to a feature spec under `docs/mvp/features/` or the demo slice (`docs/mvp/demo-slice.md`). Read the architecture doc for cross-cutting rules before proposing design or code.
+Every implementation change must trace to a feature spec under `spec/features/` or the roadmap (`spec/constitution/roadmap.md`). Read `spec/constitution/mission.md` for cross-cutting rules before proposing design or code.

.cursor/rules/spec-driven-workflow.mdc

@@ -7,13 +7,13 @@ alwaysApply: true
 
 ## Before coding
 
-1. Name the feature spec file (e.g. `docs/mvp/features/cheap-stocks.md`).
-2. Read `docs/mvp/architecture/architecture.md` for global constraints: point-in-time data, hard exclusions, MLflow runs, paper trading, universe rules.
+1. Name the feature spec file (e.g. `spec/features/003-cheap-stocks/spec.md`).
+2. Read `spec/constitution/mission.md` for global constraints: point-in-time data, hard exclusions, MLflow runs, paper trading, universe rules.
 3. If scope is unclear, ask the user and record the answer in the spec (open questions or decisions tables).
 
 ## During work
 
-- Do not add features without a corresponding `docs/mvp/features/` document. Create or extend the spec first.
+- Do not add features without a corresponding `spec/features/` document. Create or extend the spec first.
 - Keep changes aligned with MVP scope and "Out of MVP scope" sections in the spec.
 
 ## After implementation

.cursor/skills/commit-split/SKILL.md

@@ -54,7 +54,7 @@ Rules: imperative present tense; **lowercase** description; **no** trailing peri
 | --- | --- |
 | `docs` | `docs/`, `CONTEXT.md`, `AGENTS.md` |
 | `agents` | `.cursor/rules/` |
-| `mvp` | `docs/mvp/**` specs |
+| `mvp` | `spec/**` specs |
 | `skills` | `.cursor/skills/` |
 | `chore` | `.gitignore`, repo hygiene with no domain doc change |
 

.cursor/skills/grill-with-docs/ADR-FORMAT.md

@@ -1,8 +1,8 @@
 # ADR Format
 
-ADRs live in `docs/adr/` and use sequential numbering: `0001-slug.md`, `0002-slug.md`, etc.
+ADRs live in `spec/adr/` and use sequential numbering: `0001-slug.md`, `0002-slug.md`, etc.
 
-Create the `docs/adr/` directory lazily — only when the first ADR is needed.
+Create the `spec/adr/` directory lazily — only when the first ADR is needed.
 
 ## Template
 
@@ -24,7 +24,7 @@ Only include these when they add genuine value. Most ADRs won't need them.
 
 ## Numbering
 
-Scan `docs/adr/` for the highest existing number and increment by one.
+Scan `spec/adr/` for the highest existing number and increment by one.
 
 ## When to offer an ADR
 

.cursor/skills/grill-with-docs/SKILL.md

@@ -43,13 +43,13 @@ If a `CONTEXT-MAP.md` exists at the root, the repo has multiple contexts. The ma
 ├── src/
 │   ├── ordering/
 │   │   ├── CONTEXT.md
-│   │   └── docs/adr/                 ← context-specific decisions
+│   │   └── spec/adr/                 ← context-specific decisions
 │   └── billing/
 │       ├── CONTEXT.md
-│       └── docs/adr/
+│       └── spec/adr/
 ```
 
-Create files lazily — only when you have something to write. If no `CONTEXT.md` exists, create one when the first term is resolved. If no `docs/adr/` exists, create it when the first ADR is needed.
+Create files lazily — only when you have something to write. If no `CONTEXT.md` exists, create one when the first term is resolved. If no `spec/adr/` exists, create it when the first ADR is needed.
 
 ## During the session
 

.cursor/skills/improve-codebase-architecture/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: improve-codebase-architecture
-description: Find deepening opportunities in a codebase, informed by the domain language in CONTEXT.md and the decisions in docs/adr/. Use when the user wants to improve architecture, find refactoring opportunities, consolidate tightly-coupled modules, or make a codebase more testable and AI-navigable.
+description: Find deepening opportunities in a codebase, informed by the domain language in CONTEXT.md and the decisions in spec/adr/. Use when the user wants to improve architecture, find refactoring opportunities, consolidate tightly-coupled modules, or make a codebase more testable and AI-navigable.
 ---
 
 # Improve Codebase Architecture

.cursor/skills/setup-matt-pocock-skills/SKILL.md

@@ -23,7 +23,7 @@ Look at the current repo to understand its starting state. Read whatever exists;
 - `git remote -v` and `.git/config` — is this a GitHub repo? Which one?
 - `AGENTS.md` and `CLAUDE.md` at the repo root — does either exist? Is there already an `## Agent skills` section in either?
 - `CONTEXT.md` and `CONTEXT-MAP.md` at the repo root
-- `docs/adr/` and any `src/*/docs/adr/` directories
+- `spec/adr/` and any `src/*/spec/adr/` directories
 - `.cursor/rules/` — do `issue-tracker.md`, `triage-labels.md`, and `domain.md` already exist?
 - `.scratch/` — sign that a local-markdown issue tracker convention is already in use
 
@@ -60,11 +60,11 @@ Default: each role's string equals its name. Ask the user if they want to overri
 
 **Section C — Domain docs.**
 
-> Explainer: Some skills (`improve-codebase-architecture`, `diagnose`, `tdd`) read a `CONTEXT.md` file to learn the project's domain language, and `docs/adr/` for past architectural decisions. They need to know whether the repo has one global context or multiple (e.g. a monorepo with separate frontend/backend contexts) so they look in the right place.
+> Explainer: Some skills (`improve-codebase-architecture`, `diagnose`, `tdd`) read a `CONTEXT.md` file to learn the project's domain language, and `spec/adr/` for past architectural decisions. They need to know whether the repo has one global context or multiple (e.g. a monorepo with separate frontend/backend contexts) so they look in the right place.
 
 Confirm the layout:
 
-- **Single-context** — one `CONTEXT.md` + `docs/adr/` at the repo root. Most repos are this.
+- **Single-context** — one `CONTEXT.md` + `spec/adr/` at the repo root. Most repos are this.
 - **Multi-context** — `CONTEXT-MAP.md` at the root pointing to per-context `CONTEXT.md` files (typically a monorepo).
 
 ### 3. Confirm and edit

.cursor/skills/setup-matt-pocock-skills/domain.md

@@ -6,7 +6,7 @@ How the engineering skills should consume this repo's domain documentation when
 
 - **`CONTEXT.md`** at the repo root, or
 - **`CONTEXT-MAP.md`** at the repo root if it exists — it points at one `CONTEXT.md` per context. Read each one relevant to the topic.
-- **`docs/adr/`** — read ADRs that touch the area you're about to work in. In multi-context repos, also check `src/<context>/docs/adr/` for context-scoped decisions.
+- **`spec/adr/`** — read ADRs that touch the area you're about to work in. In multi-context repos, also check `src/<context>/spec/adr/` for context-scoped decisions.
 
 If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The producer skill (`/grill-with-docs`) creates them lazily when terms or decisions actually get resolved.
 
@@ -17,7 +17,7 @@ Single-context repo (most repos):
 ```
 /
 ├── CONTEXT.md
-├── docs/adr/
+├── spec/adr/
 │   ├── 0001-event-sourced-orders.md
 │   └── 0002-postgres-for-write-model.md
 └── src/
@@ -28,14 +28,14 @@ Multi-context repo (presence of `CONTEXT-MAP.md` at the root):
 ```
 /
 ├── CONTEXT-MAP.md
-├── docs/adr/                          ← system-wide decisions
+├── spec/adr/                          ← system-wide decisions
 └── src/
     ├── ordering/
     │   ├── CONTEXT.md
-    │   └── docs/adr/                  ← context-specific decisions
+    │   └── spec/adr/                  ← context-specific decisions
     └── billing/
         ├── CONTEXT.md
-        └── docs/adr/
+        └── spec/adr/
 ```
 
 ## Use the glossary's vocabulary

.gitignore

@@ -13,6 +13,8 @@ data/*
 !data/reference/**
 *hacienda*
 *portfolio*
+!spec/features/*portfolio*/
+!spec/features/*portfolio*/**
 .DS_Store
 backup*
 notebooks/*