heyspex 0.1.0

package/README.md

@@ -0,0 +1,157 @@
+# HeySpex
+
+> **Deterministic SDLC engine for AI dev, idea to ship.**
+
+HeySpex sits between "I have an idea" and "an AI agent writes code" - it distills ideas into context-window-sized plans that agents build correctly the first time. This page is the team-member onboarding walk-through: it takes you from an empty computer to your first claimed spec, and links the authoritative doc for every step instead of duplicating it.
+
+## Machine setup
+
+Prerequisites: Node.js `>=20 <25` (tested on 22.x), npm 10.x, git. No local database - HeySpex uses a cloud Postgres (Neon). Only if you will work on the Windows Companion tray app: the [.NET 8 SDK](https://dotnet.microsoft.com/download/dotnet/8.0) and [PowerShell 7](https://learn.microsoft.com/powershell/scripting/install/installing-powershell-on-windows) (`pwsh`).
+
+```bash
+# 1. Clone
+git clone https://github.com/pwhermanson/workflow-protocol.git
+cd workflow-protocol
+
+# 2. Install - this is an npm workspace; one install covers the root
+#    CLI/scripts, the Console app, and the companion extension.
+npm install
+
+# 3. Wire up the agent tooling - MCP server, lifecycle hooks, skills,
+#    slash commands, statusline, git hooks. Idempotent: run it any time,
+#    including after a git pull.
+npm run setup
+
+# 4. Verify every surface. Exits non-zero if something is missing and
+#    names the exact command that fixes it.
+npm run doctor
+```
+
+Notes that save people time:
+
+- `npm run setup` is the same as `npm run doctor -- --fix`.
+- The agent's `heyspex_*` MCP tools appear only after the agent session restarts - Claude Code and Cursor read MCP config once at startup, so restart or reconnect after the first setup. Then confirm: `/mcp` lists `heyspex` as connected and `/hs-next` returns on-deck work.
+- `.git/hooks/` is never cloned, so the pre-commit hook is the step people miss on a new machine - `doctor` checks for it explicitly (`npm run hooks:install` covers git hooks alone).
+- Editor wiring in full detail, including turning the whole layer off with `npm run heyspex:off` / back on with `npm run heyspex:on`: [docs/claude-code-setup.md](docs/claude-code-setup.md) for Claude Code, [docs/cursor-setup.md](docs/cursor-setup.md) for Cursor, [docs/driving-heyspex-from-copilot.md](docs/driving-heyspex-from-copilot.md) for Copilot.
+
+Which installer is this? Three scopes, do not mix them up:
+
+- This page / `npm run setup` is the **platform admin setup** - it only makes sense inside a full checkout of this monorepo.
+- `node bin/hs.mjs install` bootstraps a **separate** project or vault to point at an existing platform checkout. It is not yet standalone - the target's MCP config still points into this repo's `vendor/heyspex-mcp/cli.mjs`.
+- A true public customer package does not exist yet - tracked in the vault under `HS-OFUB` and `HS-RMU3`.
+
+## Credentials and secrets
+
+The minimum to run the Console:
+
+```bash
+cp spex-console/.env.example spex-console/.env.local
+```
+
+Then fill in the four required keys: `DATABASE_URL` and `DATABASE_URL_UNPOOLED` (Neon Postgres), `CLERK_SECRET_KEY` and `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` (auth). Ask the project owner or a teammate for real values - never paste keys into chat, and never commit `.env.local` (it is gitignored). The remaining keys (AI providers, GitHub App, Figma sync, Sentry) are feature-specific; the app runs without them and those features just no-op.
+
+How secrets move around the team, and why they are encrypted even in a private repo:
+
+- [docs/sharing-secrets-with-your-team.md](docs/sharing-secrets-with-your-team.md) - the grant model: repo access and decrypt access are separate grants, and you need both.
+- [docs/why-heyspex-secrets.md](docs/why-heyspex-secrets.md) - the problem this solves, in plain terms.
+- [docs/agent-access-posture.md](docs/agent-access-posture.md) - what an AI coding agent can and cannot see.
+
+Companion pairing and fleet-machine credentials only matter if your role needs them - see [docs/fleet/](docs/fleet/README.md).
+
+Local credential layout and pairing mechanics: [specs/protocols/local-dev-credentials.md](specs/protocols/local-dev-credentials.md).
+
+## Dev server rules
+
+The Console dev server connects to the shared Neon database at runtime, so a few rules keep it and the database from breaking each other.
+
+- Start the Console with `npm run console:log` - it runs the same dev server but captures the log so agents can watch it instead of asking you to paste terminal output. Use `npm run console:log:lan` for anything involving the Companion's cloud relay, which is inert against a loopback console. Plain `npm run console` also works when no agent needs the log.
+- Never run these while the server is live: a database migration, a Neon reset, a dependency install, deleting `.next`, or a second `next dev`.
+- Check ground truth first: `hs server status` (or `npm run console:status`) probes what is actually listening, not a lockfile. Stop a live server before server-impacting work.
+
+| Command | What it does |
+|---|---|
+| `npm run console` | Start the spex-console Next.js dev server (`localhost:3000`) |
+| `npm run console:log` / `console:log:lan` | Same, with the log captured (LAN variant for Companion relay work) |
+| `npm run console:stop` | Stop the console (works from any terminal) |
+| `npm run console:status` | Is the console running, and on which port |
+| `npm run companion` | Start the Windows tray companion (builds on first run if needed) |
+| `npm run companion:stop` / `companion:status` | Quit the companion / is it running |
+
+Both commands preflight their deps: the console fails fast if `npm install` is needed, the companion fails fast if the .NET 8 SDK is missing. Full procedure: [specs/protocols/dev-server-lifecycle-and-db-safety.md](specs/protocols/dev-server-lifecycle-and-db-safety.md).
+
+## How work happens
+
+The vault under `specs/` is the system of record. It is git-tracked markdown - specs, tasks, epics, research, memory, protocols - cross-linked with `[[wikilinks]]`. There is no separate tracker or planning database; the files are the data, and full history is `git log`.
+
+Work flows through gates: an idea is **captured**, grounded into **research**, then broken down into **milestone, epic, and task** specs, each task sized to fit one AI context window. Agents **claim** a spec, work its acceptance criteria, report progress, and **submit it for review**. Agents never commit - a dirty tree is the expected hand-off, and the human commits on review Pass. Spec ids are server-minted, never hand-picked ([specs/protocols/vault-id-assignment-protocol.md](specs/protocols/vault-id-assignment-protocol.md)).
+
+The seat model in one paragraph: the owner makes the judgment calls, reviews, and commits. The coding agent you drive in this repo holds the COO seat - it orchestrates, gates quality, and talks to the owner. Mechanical work (build, breakdown, critique, research) is routed by `dev-factory/` to a local model fleet, escalating to a cloud model only when a task genuinely needs it. [CLAUDE.md](CLAUDE.md) is the always-loaded agent contract that makes agents follow all of this without being asked.
+
+Where things live:
+
+| Path | What it is |
+|---|---|
+| `specs/` | The vault - the system of record |
+| `spex-console/` | The Console, a Next.js app for browsing and planning the vault |
+| `companion/` | Windows tray companion plus the browser extension |
+| `vendor/heyspex-mcp/` | The MCP server that exposes vault operations as agent tools |
+| `bin/hs.mjs` | The `hs` CLI - the same operations from a terminal |
+| `dev-factory/` | Multi-agent routing config for the model fleet |
+
+## Dev and prod mode
+
+Every machine points somewhere: a console (local or cloud), a read tier, and a write mode. `hs dev` shows what your machine currently points at, and `/hs-dev mode:local|cloud|prod` (or `hs dev mode <target>`) flips it. The choice is machine-local - it lives under `.heyspex/`, is gitignored, and never lands in a commit, so switching your own machine cannot affect a teammate's.
+
+## Your first claimed spec
+
+1. In your agent session, run `/hs-next`. It returns the on-deck work as a ready-to-execute prompt.
+2. The agent asks once to confirm the claim. Say yes, and it claims the spec and starts - no second ask.
+3. Work the acceptance criteria. The agent reports progress after each one.
+4. When every criterion is met, the agent submits the spec for review. Nobody hand-edits `status:` in frontmatter - the status API handles it.
+5. Leave the working tree dirty. The owner reviews and commits on Pass. How a session ends properly: [specs/protocols/session-close-protocol.md](specs/protocols/session-close-protocol.md).
+
+If `/hs-next` or the `heyspex_*` tools are missing, run `npm run doctor` and restart the agent session.
+
+## Reference shelf
+
+Look-up material, not required reading. Start with the [glossary](specs/glossary.md) when a term is unfamiliar.
+
+### Day-one protocols
+
+The seven protocols that are mandatory early reading:
+
+| Protocol | Why day one |
+|---|---|
+| [session-close-protocol](specs/protocols/session-close-protocol.md) | How every working session ends - what gets recorded, what never gets committed. |
+| [dev-server-lifecycle-and-db-safety](specs/protocols/dev-server-lifecycle-and-db-safety.md) | The rules that keep the shared Neon database and a live dev server from breaking each other. |
+| [local-dev-credentials](specs/protocols/local-dev-credentials.md) | Where local credentials live and how pairing works. |
+| [memory-protocol](specs/protocols/memory-protocol.md) | When and how durable lessons and decisions get filed. |
+| [research-capture-protocol](specs/protocols/research-capture-protocol.md) | The capture to research road every idea travels. |
+| [vault-id-assignment-protocol](specs/protocols/vault-id-assignment-protocol.md) | Why ids are server-minted and never hand-picked. |
+| [mcp-slash-surface-protocol](specs/protocols/mcp-slash-surface-protocol.md) | How the MCP tools and slash commands relate across Claude Code and Cursor. |
+
+The full folder (`specs/protocols/`, about 70 protocols) is reference material - agents fetch them on demand via `heyspex_get_procedure`.
+
+### Which docs apply to you
+
+| Your role | Read these |
+|---|---|
+| Everyone | [docs/claude-code-setup.md](docs/claude-code-setup.md) or [docs/cursor-setup.md](docs/cursor-setup.md) (whichever editor you drive), [docs/sharing-secrets-with-your-team.md](docs/sharing-secrets-with-your-team.md) |
+| Console work | [dev-server-lifecycle-and-db-safety](specs/protocols/dev-server-lifecycle-and-db-safety.md), the design-system registry under `spex-console/public/design-system/` |
+| Companion work | .NET 8 SDK plus `pwsh` prerequisites above, [docs/fleet/companion-app-distribution.md](docs/fleet/companion-app-distribution.md), [docs/fleet/cloud-relay-add-machine.md](docs/fleet/cloud-relay-add-machine.md), [docs/fleet/chrome-extension-distribution.md](docs/fleet/chrome-extension-distribution.md) |
+| Fleet machines | [docs/fleet/README.md](docs/fleet/README.md), [docs/fleet/release-runbook.md](docs/fleet/release-runbook.md), [scripts/public-install/README.md](scripts/public-install/README.md) |
+
+### Deeper reading
+
+- [specs/heyspex-north-star.md](specs/heyspex-north-star.md) - the vision and constitution.
+- [specs/HS-DOC-architecture-foundations.md](specs/HS-DOC-architecture-foundations.md) - the architecture map and milestones.
+- [specs/entity-model.md](specs/entity-model.md) - entity kinds, frontmatter, folder layout.
+- [plugins/heyspex/README.md](plugins/heyspex/README.md) - the plugin packaging prototype for bootstrapping other repos.
+
+### Legacy tooling
+
+This repo also contains `workflow-pm`, an earlier standalone PM tool built on beads (`bd`), which was retired as the system of record when the vault replaced it (see [specs/migration-from-bd.md](specs/migration-from-bd.md)). Its reference docs live in [MULTI_AGENT_PM_PROTOCOL.md](MULTI_AGENT_PM_PROTOCOL.md), [SETUP.md](SETUP.md), [IMPLEMENTATION_ROADMAP_PROTOCOL.md](IMPLEMENTATION_ROADMAP_PROTOCOL.md), and [pm-control-center/README.md](pm-control-center/README.md). None of it is needed for day-to-day HeySpex work.
+
+## License
+
+MIT - use freely, modify as needed, no attribution required.