mindsystem-cc 4.4.0 → 4.4.2

package/README.md

@@ -2,21 +2,44 @@
 
 ![Mindsystem Bento Grid](assets/bento-image.webp)
 
-Amplifies every step of the development workflow you already follow — discovery, research, design, planning, execution, verification. Each one refined, parallelized, and compounded into persistent knowledge. Built for lean teams and solo builders who want to multiply their output without giving up control.
+# Mindsystem
 
-```bash
-npx mindsystem-cc
-```
+Amplifies every step of the development workflow you already follow.
 
 [![npm version](https://img.shields.io/npm/v/mindsystem-cc?style=flat-square&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/mindsystem-cc)
+[![npm downloads](https://img.shields.io/npm/dm/mindsystem-cc?style=flat-square)](https://www.npmjs.com/package/mindsystem-cc)
 [![License](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE)
+[![Built for Claude Code](https://img.shields.io/badge/built_for-Claude_Code-D97706?style=flat-square)](https://docs.anthropic.com/en/docs/claude-code)
 
-[Why Mindsystem](#why-mindsystem) · [How it works](#how-it-works) · [Walkthrough](#end-to-end-walkthrough) · [Features](#features) · [Quick start](#quick-start) · [.planning](#the-planning-directory) · [Config](#configuration) · [Commands](#command-reference) · [Troubleshooting](#troubleshooting)
+Discovery, research, design, planning, execution, verification — each one refined, parallelized, and compounded into persistent knowledge. Built for lean teams and solo builders who want to multiply their output without giving up control.
+
+[Quick start](#quick-start) · [Walkthrough](#end-to-end-walkthrough) · [Features](#features) · [Commands](#command-reference)
 
 </div>
 
 ---
 
+## Quick start
+
+```bash
+npx mindsystem-cc
+```
+
+Then `/ms:new-project` to initialize. See the [full walkthrough](#end-to-end-walkthrough) for the complete feature-building loop, or `/ms:progress` to pick up where you left off.
+
+---
+
+## What's new in v4.4
+
+- **Knowledge quality gate** — consolidator and compounder filter extracted knowledge through signal density enforcement, eliminating noise entries that wouldn't change how an LLM implements code.
+- **User journey browser verification** — end-to-end click/fill/submit testing instead of screenshot-only observation. Catches unreachable pages with no navigation path from the UI.
+- **Single-plan mode (default)** — one plan per phase, eliminating multi-agent orchestration overhead with 1M context windows.
+- **Full phase specification** for add-phase and insert-phase — both commands now derive goal, success criteria, and requirements mapping.
+
+See [CHANGELOG.md](CHANGELOG.md) for the complete history.
+
+---
+
 ## Why Mindsystem
 
 Fully autonomous coding tools take a spec and run until a product emerges. That works for prototypes. Mindsystem takes the opposite approach — it follows the workflow a thorough engineer already uses, and amplifies each step:
@@ -87,7 +110,7 @@ Execution happens in fresh subagent contexts, so each plan gets up to 200k token
 
 ### Project setup
 
-Before building features, initialize the project once with `/ms:new-project`. For existing codebases, also run `/ms:map-codebase` (analyzes your stack, conventions, and architecture into 7 structured documents) and `/ms:doctor` (validates config and generates per-subsystem knowledge files from source code). See [Quick start](#quick-start) for the exact sequences.
+Before building features, initialize the project once with `/ms:new-project`. For existing codebases, also run `/ms:map-codebase` (analyzes your stack, conventions, and architecture into 7 structured documents) and `/ms:doctor` (validates config and generates per-subsystem knowledge files from source code). See [Getting started](#getting-started) for the exact sequences.
 
 Everything below is the feature-building loop, identical for new and existing projects.
 
@@ -277,6 +300,10 @@ Requirements you want but haven't shipped yet are tracked in `PROJECT.md` with o
 
 `/ms:add-todo` with Linear-inspired metadata: priority (1-4), estimate (XS-XL), inferred subsystem. Todos live as flat files in `.planning/todos/`. Address them later via `/ms:adhoc`, which reads the problem description, executes the work, and moves the todo to `done/`.
 
+### Task tracker integration
+
+Configure a Linear connection via `/ms:config` and pass ticket IDs directly to `/ms:adhoc` (e.g., `/ms:adhoc MIN-123`). The system auto-fetches the ticket's title and description as work context, tags commits with the ticket ID, and on completion posts a solution summary, attaches the commit, and marks the ticket done. Zero overhead when unconfigured — the integration is lazy-loaded only when a ticket ID is detected.
+
 ### Codebase mapping
 
 `/ms:map-codebase` spawns 4 parallel agents producing 7 structured documents: stack, architecture, conventions, testing, integrations, directory structure, and concerns. Use on brownfield projects so Mindsystem respects your existing patterns.
@@ -297,7 +324,7 @@ Requirements you want but haven't shipped yet are tracked in `PROJECT.md` with o
 
 ---
 
-## Quick start
+## Getting started
 
 ### Project setup (one-time)
 
@@ -324,6 +351,7 @@ Once the project is set up, the workflow is the same for new and existing codeba
 ```
 /ms:new-milestone               # Discover what to build next
 /ms:create-roadmap              # Define requirements, map to phases
+/ms:discuss-phase 1             # Gather context before planning
 /ms:plan-phase 1                # Create detailed plan
 /ms:execute-phase 1             # Run in fresh subagents
 /ms:verify-work 1               # Manual acceptance testing
@@ -498,7 +526,7 @@ Full docs live in `/ms:help`.
 | `/ms:execute-phase <number>` | Run all unexecuted plans in fresh subagents |
 | `/ms:verify-work [number]` | Batched manual UAT with inline fixes |
 | `/ms:debug [description]` | Structured debugging that survives `/clear` |
-| `/ms:adhoc <description>` | Knowledge-aware execution for discovered work |
+| `/ms:adhoc <description>` | Knowledge-aware execution for discovered work or Linear ticket IDs |
 | `/ms:compound [input]` | Compound out-of-pipeline changes into knowledge files |
 | `/ms:add-phase <description>` | Append a new phase to the roadmap |
 | `/ms:insert-phase <after> <description>` | Insert urgent work between phases |

package/agents/ms-compounder.md

@@ -25,6 +25,10 @@ You are a Mindsystem knowledge compounder spawned by the compound workflow to up
 
 </inputs>
 
+<references>
+@~/.claude/mindsystem/references/knowledge-quality.md
+</references>
+
 <extraction_guide>
 
 ## What to Extract From Raw Changes
@@ -59,15 +63,19 @@ ls .planning/knowledge/*.md 2>/dev/null
 
 Read only the files matching confirmed affected subsystems. On first run, `.planning/knowledge/` may not exist — start fresh.
 
-## Step 3: Extract Knowledge From Changes
+## Step 3: Classify and Extract Knowledge From Changes
+
+Classify each change signal before extraction:
 
-Apply the extraction guide to the change content.
+| Signal Type | Action |
+|------------|--------|
+| Decision with rationale (chose X over Y because Z) | Extract |
+| Structural pattern (how components connect, data flows) | Extract |
+| Non-obvious pitfall or gotcha | Extract |
+| Code-derivable detail (schema fields, component props, config values) | Skip |
+| Implementation description without alternative considered | Skip |
 
-Focus on:
-- **Decisions with rationale** — not just "used X" but "used X because Y"
-- **Structural patterns** — how components connect, data flows, API contracts
-- **Gotchas discovered** — failure modes, workarounds, non-obvious behavior
-- **Significant file changes** — new entry points, renamed modules, deleted code
+Apply the extraction guide to change content that passes classification. Then apply the knowledge-quality.md filtering test — drop entries that fail. For entries that pass, check existing knowledge files for cross-subsystem duplication — use `(see {subsystem})` cross-references instead of duplicating.
 
 ## Step 4: Merge Into Existing Knowledge
 
@@ -81,6 +89,8 @@ For each affected subsystem, edit the knowledge file to reflect current state:
 
 Use `Edit` for existing files — targeted changes preserve content you haven't inspected. Use `Write` only for new files (subsystem has no knowledge file yet).
 
+While merging, review the touched file's existing entries through the same quality gate. Remove entries that are now code-derivable, superseded by new decisions, or duplicated in another subsystem's knowledge file. This is opportunistic maintenance during normal writes, not a full audit.
+
 ## Step 5: Update Knowledge Files and Return Report
 
 ```bash
@@ -142,4 +152,6 @@ If changes suggest a subsystem not in the confirmed list, note it as a proposal
 - [ ] Report returned with update counts
 - [ ] Empty sections omitted from knowledge files
 - [ ] Existing knowledge files read for affected subsystems only
+- [ ] Extracted entries pass the knowledge-quality.md filtering test
+- [ ] No cross-subsystem duplication (cross-references used instead)
 </success_criteria>

package/agents/ms-consolidator.md

@@ -41,6 +41,10 @@ You are a Mindsystem knowledge consolidator spawned by execute-phase after plan
 
 </inputs>
 
+<references>
+@~/.claude/mindsystem/references/knowledge-quality.md
+</references>
+
 <extraction_guide>
 
 ## What to Extract Per Artifact
@@ -68,7 +72,7 @@ You are a Mindsystem knowledge consolidator spawned by execute-phase after plan
 | DESIGN Content | Target Knowledge Section |
 |----------------|------------------------|
 | Wireframe layouts, inline annotations | Design |
-| Design tokens (colors, spacing, typography) | Design |
+| Design reasoning (why this approach, not pixel values) | Design |
 | Behavior notes, interaction patterns | Design |
 | States tables, platform hints | Design |
 
@@ -135,6 +139,8 @@ Apply the extraction guide to each artifact:
 
 Extract knowledge, not descriptions. "Using React" is not knowledge. "Using React over Vue because of ecosystem maturity and team familiarity" is knowledge.
 
+Apply the knowledge-quality.md filtering test to each extracted entry before assigning it to a subsystem. Drop entries that fail. For entries that pass, check existing knowledge files for cross-subsystem duplication — use `(see {subsystem})` cross-references instead of duplicating.
+
 ## Step 6: Merge Into Knowledge Files
 
 For each affected subsystem, edit the knowledge file to reflect current state:
@@ -147,6 +153,8 @@ For each affected subsystem, edit the knowledge file to reflect current state:
 
 Use `Edit` for existing files — targeted changes preserve content you haven't inspected. Use `Write` only for new files (subsystem has no knowledge file yet).
 
+While merging, review the touched file's existing entries through the same quality gate. Remove entries that are now code-derivable, superseded by new decisions, or duplicated in another subsystem's knowledge file. This is opportunistic maintenance during normal writes, not a full audit.
+
 ## Step 7: Update Knowledge Files
 
 ```bash
@@ -225,5 +233,7 @@ Use `+N` for new entries added, `updated` for sections rewritten with changes, `
 - [ ] Empty sections omitted from knowledge files
 - [ ] PLAN.md files deleted from phase directory
 - [ ] CONTEXT.md, DESIGN.md, RESEARCH.md, SUMMARY.md preserved
+- [ ] Extracted entries pass the knowledge-quality.md filtering test
+- [ ] No cross-subsystem duplication (cross-references used instead)
 - [ ] No commits made
 </success_criteria>

package/commands/ms/config.md

@@ -53,7 +53,7 @@ git remote -v 2>/dev/null || echo "NO_REMOTE"
 2. **Code reviewers** — adhoc: {value or "not set"}, phase: {value or "not set"}, milestone: {value or "not set"}
 3. **Gitignore** — {current .planning/ patterns or "no .planning/ patterns"}
 4. **Mockups** — open: {auto / ask / off}
-5. **Browser verification** — {enabled / disabled}
+5. **Browser verification** — {enabled / disabled}, web project: {yes / no / auto-detect}
 6. **Plan mode** — {single plan (default) / multi-plan}
 7. **Task tracker** — {type + cli path, or "none"}
 ```
@@ -198,9 +198,30 @@ Map selection:
 Update config.json:
 
 ```bash
-ms-tools config-set browser_verification --json '{"enabled": true}'   # or false
+ms-tools config-set browser_verification.enabled --json 'true'   # or false
 ```
 
+**If enabled**, detect and confirm web project status:
+
+```bash
+ms-tools detect-web
+```
+
+Present the auto-detection result via AskUserQuestion:
+- header: "Web project detection"
+- question: "Is this a web project with a browser-renderable UI? Auto-detection returned: {detected result}"
+- options:
+  - "Yes — this is a web project" (recommended if detected)
+  - "No — this is not a web project"
+  - "Auto-detect (don't persist)" — remove any existing override
+
+Map selection:
+- "Yes" → `ms-tools config-set browser_verification.web_project --json 'true'`
+- "No" → `ms-tools config-set browser_verification.web_project --json 'false'`
+- "Auto-detect" → `ms-tools config-delete browser_verification.web_project`
+
+**If disabled**, skip the web_project question.
+
 </step>
 
 <step name="multi_plan">

package/commands/ms/doctor.md

@@ -145,7 +145,7 @@ If "Review each" → use AskUserQuestion for each failed check with its details
 
 Apply fixes in dependency order: fix_subsystems → fix_milestone_dirs → fix_milestone_naming → fix_phase_archival → fix_plan_cleanup → fix_phase_dirs → fix_knowledge. Skip any fix whose check passed or was skipped by user.
 
-Phase summaries are resolved by fix_phase_archival. CLI wrapper failures have specific fixes: bin dir not in PATH → restart Claude Code session; missing wrappers or bin dir → re-run `npx mindsystem-cc`; uv not found → `curl -LsSf https://astral.sh/uv/install.sh | sh`. WARN checks (Research API Keys, missing uv) are informational — no automated fix, only displayed in the report.
+Phase summaries are resolved by fix_phase_archival. CLI wrapper failures have specific fixes: bin dir not in PATH → restart Claude Code session; missing wrappers or bin dir → re-run `npx mindsystem-cc`; uv not found → `curl -LsSf https://astral.sh/uv/install.sh | sh`. WARN checks (Research API Keys, missing uv) are informational — no automated fix, only displayed in the report. Research API Keys check provides platform-aware setup guidance (shell export on macOS/Linux, settings.json on Windows) and checks both environment variables and `~/.claude/settings.json` env section as fallback.
 </step>
 
 <step name="apply_fixes">

package/commands/ms/help.md

@@ -108,7 +108,7 @@ Initialize new project with brief and configuration.
 Usage: `/ms:new-project`
 
 **`/ms:config`**
-Configure Mindsystem preferences — code reviewers, mockup preferences, browser verification, plan mode, gitignore patterns, git remote.
+Configure Mindsystem preferences — code reviewers, mockup preferences, browser verification, plan mode, gitignore patterns, git remote, task tracker.
 
 - Use when: you want to set up code review agents, mockup open behavior, manage which .planning/ artifacts are git-ignored, or push your repo to GitHub.
 - Edits `.planning/config.json` and `.gitignore`
@@ -366,11 +366,13 @@ Execute discovered work with knowledge-aware planning and execution.
 - Use when: you discover work mid-session that can be completed in a single context window without multi-phase orchestration.
 - Bridges the gap between `/ms:add-todo` (capture for later) and `/ms:insert-phase` (multi-plan coordination)
 - Knowledge-aware: loads relevant knowledge files before planning, consolidates learnings after execution
+- Accepts Linear ticket IDs when task tracker is configured via `/ms:config` — auto-fetches context, tags commits, and finalizes the ticket on completion
 - Spawns Explore agents for codebase understanding, ms-adhoc-planner for plan creation, ms-executor for execution
 - Creates per-execution artifacts in `.planning/adhoc/{timestamp}-{slug}/`
 - Updates knowledge files via ms-consolidator after execution
 
 Usage: `/ms:adhoc Fix auth token not refreshing on 401`
+Usage: `/ms:adhoc MIN-123` (Linear ticket — auto-fetches context, finalizes on completion)
 Usage: `/ms:adhoc Refactor API error handling to use consistent format`
 
 ### Utility Commands

package/commands/ms/new-milestone.md

@@ -276,7 +276,9 @@ Milestone name: $ARGUMENTS (optional — will emerge during discovery if not pro
 
 19. **Route to next step:**
 
-    Default to `/ms:research-milestone` — domain research improves roadmap quality for most milestones. Only recommend `/ms:create-roadmap` directly when the domain is clearly familiar, no open questions surfaced, and there are no external APIs, new libraries, or unfamiliar patterns involved.
+    Determine primary suggestion:
+    - Default: `/ms:research-milestone` — domain research improves roadmap quality for most milestones
+    - Only `/ms:create-roadmap` when domain is clearly familiar, no open questions surfaced, and no external APIs, new libraries, or unfamiliar patterns
 
     ```
     Milestone [Name] initialized.
@@ -289,17 +291,20 @@ Milestone name: $ARGUMENTS (optional — will emerge during discovery if not pro
 
     ## ▶ Next Up
 
-    `/ms:[recommended-command]` — [one-line reason from conversation]
+    `/ms:{suggested}` — [one-line reason from conversation]
 
     <sub>`/clear` first → fresh context window</sub>
 
     ---
 
-    **Also available:** `/ms:[alternative-command]` — [brief reason]
+    **Also available:**
+    - `/ms:{alternative}` — [brief reason]
 
     ---
     ```
 
+    `{suggested}` and `{alternative}` are always one of: `research-milestone`, `create-roadmap`.
+
 </process>
 
 <success_criteria>

package/mindsystem/references/knowledge-quality.md

@@ -0,0 +1,89 @@
+<knowledge_quality>
+
+Shared quality gate for knowledge extraction. Referenced by ms-consolidator and ms-compounder agents.
+
+<filtering_principle>
+
+**The single test:** "Would an LLM implement this incorrectly without this entry?"
+
+If yes — the entry earns its place. If an LLM with access to the codebase would get it right anyway, the entry is noise.
+
+What passes the test:
+- Conventions that differ from LLM defaults or framework norms
+- Failed experiments and why they failed (prevents re-discovery)
+- Non-obvious bugs, gotchas, or workarounds
+- Decisions where the alternative was reasonable (the "because" matters)
+- Cross-cutting patterns not visible from a single file
+
+</filtering_principle>
+
+<fails_the_test>
+
+These categories consistently fail the filtering test. Drop them during extraction.
+
+| Category | Why It Fails | Example |
+|----------|-------------|---------|
+| Design tokens (colors, spacing, typography) | Readable from code/config files | "Primary: #6366F1, spacing-md: 16px" |
+| Component API descriptions | Readable from component source | "SubscriptionCard accepts `plan`, `onSelect` props" |
+| Schema/model field listings | Readable from schema files | "User has fields: id, email, name, createdAt" |
+| Version pins without rationale | Readable from package.json/lockfile | "Using React 18.2.0" |
+| Decisions without alternatives | No "because" = no reusable knowledge | "Using Tailwind for styling" (vs. what?) |
+| Implementation descriptions | Restates what the code does | "Login endpoint hashes password and returns JWT" |
+
+</fails_the_test>
+
+<passes_the_test>
+
+Concrete examples that earn their place — each would cause incorrect implementation without the entry.
+
+1. **FieldMask casing (gRPC):** FieldMask paths must use camelCase in JSON, not snake_case — proto3 JSON mapping silently drops snake_case paths. LLMs default to snake_case matching proto definitions.
+
+2. **keepAlive auto-dispose (Flutter):** Riverpod providers with `keepAlive()` in `autoDispose` family providers — calling `keepAlive()` inside `ref.onDispose` creates a retain cycle. Dispose callback never fires, provider leaks. Place `keepAlive()` in the provider body before any async gap.
+
+3. **HiveField index stability:** HiveField indices are permanent storage keys — changing an index silently corrupts existing user data. New fields must use the next unused index, never reuse or reorder.
+
+4. **do/while pagination (API):** Firestore `startAfter` cursor pagination requires do/while, not while — a while loop with an empty-page exit condition misses the last partial page when `limit` equals page size exactly.
+
+5. **Payment timeout (Stripe):** Stripe webhook delivery retries for up to 72 hours. Payment confirmation UI must show "processing" state, not assume success/failure within a session.
+
+6. **Interceptor ordering (Dio):** Dio interceptors run in addition order for requests but reverse order for responses/errors. Auth token injection must be added first to run last on error (so retry logic sees the refreshed token).
+
+</passes_the_test>
+
+<decision_quality_test>
+
+Not every decision is knowledge. Apply this secondary filter:
+
+**"Could a reasonable agent have chosen differently?"**
+
+- **Pass:** "jose over jsonwebtoken — better TypeScript types and actively maintained" → Yes, jsonwebtoken is the more common choice. The rationale prevents revisiting.
+- **Pass:** "httpOnly cookies over localStorage for JWT — XSS prevention" → Yes, localStorage is the LLM default. Without this entry, an LLM would likely use localStorage.
+- **Fail:** "Using TypeScript for type safety" → No reasonable agent would choose plain JS for a new project. This is a default, not a decision.
+- **Fail:** "Using ESLint for linting" → No alternative was seriously considered. Not knowledge.
+
+</decision_quality_test>
+
+<cross_subsystem_dedup>
+
+Before writing an entry, check whether it already exists in another subsystem's knowledge file.
+
+- If the entry belongs primarily to another subsystem, add a cross-reference: `(see {subsystem})` instead of duplicating.
+- If the entry spans multiple subsystems equally, place it in the most upstream subsystem and cross-reference from others.
+- If an existing duplicate is found during extraction, remove it from the less-relevant file and cross-reference.
+
+</cross_subsystem_dedup>
+
+<existing_content_review>
+
+On every write to a knowledge file, review the touched file's existing entries:
+
+- **Still relevant?** Remove entries for features/patterns that no longer exist.
+- **Code-derivable now?** Remove entries that were non-obvious when written but are now self-evident from the codebase (e.g., a pattern that was novel is now standard in the project).
+- **Superseded?** Update or remove entries contradicted by new decisions.
+- **Duplicated?** Check against other knowledge files — deduplicate using cross-references.
+
+This is opportunistic maintenance during normal writes, not a full audit.
+
+</existing_content_review>
+
+</knowledge_quality>

package/mindsystem/templates/knowledge.md

@@ -30,8 +30,8 @@ Template for `.planning/knowledge/{subsystem}.md` — per-subsystem knowledge fi
 
 ## Design
 
-- {Visual/UX spec, interaction pattern, or design token}
-- {Component state, layout choice, or color value}
+- {Design reasoning — why this approach, not alternatives}
+- {Interaction pattern that differs from LLM defaults}
 
 ## Pitfalls
 
@@ -54,7 +54,7 @@ Template for `.planning/knowledge/{subsystem}.md` — per-subsystem knowledge fi
 |---------|----------|-----------------|
 | **Decisions** | Choices with rationale (the "because" part) | CONTEXT.md locked decisions, RESEARCH.md recommendations, PLAN.md approach rationale, SUMMARY.md key-decisions |
 | **Architecture** | How the subsystem works, structural patterns | RESEARCH.md architecture patterns, PLAN.md implementation details, SUMMARY.md accomplishments |
-| **Design** | Visual/UX specs, interaction patterns, design tokens | DESIGN.md wireframe layouts, states tables, behavior notes, design tokens |
+| **Design** | Design reasoning, non-obvious interaction patterns (reasoning only — not tokens or values readable from code) | DESIGN.md wireframe layouts, states tables, behavior notes |
 | **Pitfalls** | What to watch out for, operational patterns | RESEARCH.md common pitfalls, SUMMARY.md issues/deviations, debug resolutions, adhoc learnings |
 | **Key Files** | Important file paths for this subsystem | SUMMARY.md key-files, PLAN.md file targets |
 
@@ -96,4 +96,19 @@ The cross-reference is navigational, not essential. Each file is self-contained
 - Fixed a bug in auth (description, not a reusable pattern)
 - Missing import in login.ts (trivial, not worth persisting)
 
+## What Doesn't Belong
+
+Apply this test to every entry: **"Would an LLM implement this incorrectly without this entry?"** If the answer is no, the entry is noise.
+
+Categories that consistently fail the test:
+
+- **Design tokens** (colors, spacing, typography) — readable from code/config files
+- **Component API descriptions** — readable from component source
+- **Schema/model field listings** — readable from schema files
+- **Version pins without rationale** — readable from package.json/lockfile
+- **Decisions without alternatives** — no "because" = no reusable knowledge ("Using Tailwind" vs. what?)
+- **Implementation descriptions** — restates what the code does
+
+**Decision quality test:** "Could a reasonable agent have chosen differently?" If no, it's a default, not a decision. "Using TypeScript for type safety" fails. "jose over jsonwebtoken for better TypeScript types" passes — jsonwebtoken is the more common choice.
+
 </guidelines>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mindsystem-cc",
-  "version": "4.4.0",
+  "version": "4.4.2",
   "description": "The engineer's meta-prompting system for Claude Code.",
   "bin": {
     "mindsystem-cc": "bin/install.js"

package/scripts/ms-tools.py

@@ -614,6 +614,18 @@ def _get_claude_config_dir() -> Path:
     return Path.home() / ".claude"
 
 
+def _get_settings_env_var(key: str) -> str:
+    """Read an env var from ~/.claude/settings.json env section."""
+    settings_path = _get_claude_config_dir() / "settings.json"
+    if not settings_path.is_file():
+        return ""
+    try:
+        settings = json.loads(settings_path.read_text(encoding="utf-8"))
+        return settings.get("env", {}).get(key, "")
+    except (json.JSONDecodeError, OSError):
+        return ""
+
+
 WEB_FRAMEWORK_DEPS = {
     "react", "react-dom", "vue", "next", "nuxt", "@angular/core",
     "svelte", "@sveltejs/kit", "solid-js", "astro", "@remix-run/react",
@@ -625,6 +637,25 @@ WEB_CONFIG_FILES = [
     "svelte.config.*", "astro.config.*", "remix.config.*",
 ]
 
+SERVERSIDE_FRAMEWORK_FILES = [
+    "artisan",               # Laravel
+    "config.ru",             # Ruby Rack (Rails, Sinatra)
+    "wp-config.php",         # WordPress
+    "wp-config-sample.php",  # WordPress (fresh install)
+]
+
+SERVERSIDE_COMPOSER_DEPS = {
+    "yiisoft/yii2", "yiisoft/yii", "laravel/framework",
+    "symfony/framework-bundle", "symfony/symfony",
+    "cakephp/cakephp", "codeigniter4/framework",
+}
+
+SERVERSIDE_GEMFILE_KEYWORDS = ["rails", "sinatra"]
+
+SERVERSIDE_PYTHON_KEYWORDS = ["django", "flask", "fastapi"]
+
+SERVERSIDE_PYTHON_FILES = ["requirements.txt", "pyproject.toml", "Pipfile"]
+
 
 def _detect_web_project(git_root: Path) -> tuple[bool, str]:
     """Detect if project is a web project. Returns (is_web, signal_description)."""
@@ -645,6 +676,46 @@ def _detect_web_project(git_root: Path) -> tuple[bool, str]:
         if list(git_root.glob(pattern)):
             return True, f"{pattern} found"
 
+    # Signal 2b: Server-side framework marker files
+    for marker in SERVERSIDE_FRAMEWORK_FILES:
+        if (git_root / marker).is_file():
+            return True, f"{marker} found"
+
+    # Signal 2c: composer.json deps
+    composer = git_root / "composer.json"
+    if composer.is_file():
+        try:
+            data = json.loads(composer.read_text(encoding="utf-8"))
+            all_deps = {**data.get("require", {}), **data.get("require-dev", {})}
+            found = SERVERSIDE_COMPOSER_DEPS & set(all_deps.keys())
+            if found:
+                return True, f"{', '.join(sorted(found))} in composer.json"
+        except (json.JSONDecodeError, OSError):
+            pass
+
+    # Signal 2d: Gemfile keywords
+    gemfile = git_root / "Gemfile"
+    if gemfile.is_file():
+        try:
+            content = gemfile.read_text(encoding="utf-8").lower()
+            for kw in SERVERSIDE_GEMFILE_KEYWORDS:
+                if kw in content:
+                    return True, f"'{kw}' in Gemfile"
+        except OSError:
+            pass
+
+    # Signal 2e: Python dependency files
+    for pyfile in SERVERSIDE_PYTHON_FILES:
+        pypath = git_root / pyfile
+        if pypath.is_file():
+            try:
+                content = pypath.read_text(encoding="utf-8").lower()
+                for kw in SERVERSIDE_PYTHON_KEYWORDS:
+                    if kw in content:
+                        return True, f"'{kw}' in {pyfile}"
+            except OSError:
+                pass
+
     # Signal 3: One level deep package.json (monorepo)
     for child_pkg in git_root.glob("*/package.json"):
         if "node_modules" in str(child_pkg):
@@ -663,7 +734,16 @@ def _detect_web_project(git_root: Path) -> tuple[bool, str]:
     if project_md.is_file():
         try:
             content = project_md.read_text(encoding="utf-8").lower()
-            web_keywords = ["react", "vue", "next.js", "nextjs", "nuxt", "angular", "svelte", "sveltekit", "astro", "remix"]
+            web_keywords = [
+                # JS frameworks
+                "react", "vue", "next.js", "nextjs", "nuxt", "angular", "svelte", "sveltekit", "astro", "remix",
+                # Server-side web frameworks
+                "yii", "laravel", "symfony", "codeigniter", "cakephp",
+                "django", "flask", "fastapi", "rails", "ruby on rails",
+                "spring boot", "spring mvc",
+                "asp.net", "blazor",
+                "wordpress",
+            ]
             for kw in web_keywords:
                 if kw in content:
                     return True, f"'{kw}' mentioned in PROJECT.md"
@@ -718,9 +798,25 @@ def cmd_browser_check(args: argparse.Namespace) -> None:
 
     # 2. Web project check
     print("\n=== Web Project Detection ===")
-    is_web, signal = _detect_web_project(git_root)
-    print(f"Web project: {is_web}")
-    print(f"Signal: {signal}")
+    web_project_override = None
+    if config_path and config_path.is_file():
+        try:
+            config = json.loads(config_path.read_text(encoding="utf-8"))
+            bv = config.get("browser_verification", {})
+            if isinstance(bv, dict) and "web_project" in bv:
+                web_project_override = bv["web_project"]
+        except (json.JSONDecodeError, OSError):
+            pass
+
+    if web_project_override is not None:
+        is_web = bool(web_project_override)
+        signal = "config override"
+        print(f"Web project: {is_web} (config override)")
+        print(f"Signal: {signal}")
+    else:
+        is_web, signal = _detect_web_project(git_root)
+        print(f"Web project: {is_web}")
+        print(f"Signal: {signal}")
 
     if not is_web:
         print("\nResult: SKIP (not a web project)")
@@ -759,6 +855,26 @@ def cmd_browser_check(args: argparse.Namespace) -> None:
     sys.exit(0)
 
 
+# ===================================================================
+# Subcommand: detect-web
+# ===================================================================
+
+
+def cmd_detect_web(args: argparse.Namespace) -> None:
+    """Expose _detect_web_project() for use by config command.
+
+    Contract:
+        Output: text — detected + signal
+        Exit codes: 0 = web project, 1 = not web project
+        Side effects: read-only
+    """
+    git_root = find_git_root()
+    is_web, signal = _detect_web_project(git_root)
+    print(f"detected: {is_web}")
+    print(f"signal: {signal}")
+    sys.exit(0 if is_web else 1)
+
+
 # ===================================================================
 # Subcommand: doctor-scan
 # ===================================================================
@@ -1131,28 +1247,50 @@ def cmd_doctor_scan(args: argparse.Namespace) -> None:
 
     # ---- CHECK 9: Research API Keys ----
     print("=== Research API Keys ===")
-    c7_key = os.environ.get("CONTEXT7_API_KEY", "")
-    pplx_key = os.environ.get("PERPLEXITY_API_KEY", "")
-    if c7_key and pplx_key:
-        print("Status: PASS")
-        print("All research API keys configured")
-        record("PASS", "Research API Keys")
-    else:
+    api_keys = {
+        "CONTEXT7_API_KEY": {
+            "enables": "library documentation lookup via Context7",
+            "without": "falls back to WebSearch/WebFetch (less authoritative)",
+            "url": "https://context7.com → copy API key",
+        },
+        "PERPLEXITY_API_KEY": {
+            "enables": "deep research via Perplexity AI",
+            "without": "falls back to WebSearch/WebFetch (less comprehensive)",
+            "url": "https://perplexity.ai/settings/api → copy API key",
+        },
+    }
+    missing_keys: list[str] = []
+    settings_only_keys: list[str] = []
+    for key_name, info in api_keys.items():
+        env_val = os.environ.get(key_name, "")
+        settings_val = _get_settings_env_var(key_name)
+        if env_val:
+            pass  # configured via environment
+        elif settings_val:
+            settings_only_keys.append(key_name)
+        else:
+            missing_keys.append(key_name)
+            print(f"{key_name}: not set")
+            print(f"  Enables: {info['enables']}")
+            print(f"  Without: {info['without']}")
+            if sys.platform == "win32":
+                print(f"  Set up:  {info['url']} → add to ~/.claude/settings.json env section")
+                print(f"           Or set via Windows System Environment Variables")
+            else:
+                shell_rc = "~/.zshrc" if sys.platform == "darwin" else "~/.bashrc"
+                print(f"  Set up:  {info['url']} → export {key_name}=<key> in {shell_rc}")
+                print(f"           Or add to ~/.claude/settings.json env section")
+    if missing_keys:
         print("Status: WARN")
-        missing_keys: list[str] = []
-        if not c7_key:
-            missing_keys.append("CONTEXT7_API_KEY")
-            print("CONTEXT7_API_KEY: not set")
-            print("  Enables: library documentation lookup via Context7")
-            print("  Without: falls back to WebSearch/WebFetch (less authoritative)")
-            print("  Set up:  https://context7.com → copy API key → export CONTEXT7_API_KEY=<key>")
-        if not pplx_key:
-            missing_keys.append("PERPLEXITY_API_KEY")
-            print("PERPLEXITY_API_KEY: not set")
-            print("  Enables: deep research via Perplexity AI")
-            print("  Without: falls back to WebSearch/WebFetch (less comprehensive)")
-            print("  Set up:  https://perplexity.ai/settings/api → copy API key → export PERPLEXITY_API_KEY=<key>")
         record("WARN", "Research API Keys")
+    else:
+        print("Status: PASS")
+        if settings_only_keys:
+            print("All research API keys configured")
+            print(f"  Note: {', '.join(settings_only_keys)} found in settings.json — restart Claude Code session to activate")
+        else:
+            print("All research API keys configured")
+        record("PASS", "Research API Keys")
     print()
 
     # ---- CHECK 10: Phase Directory Naming ----
@@ -1204,15 +1342,32 @@ def cmd_doctor_scan(args: argparse.Namespace) -> None:
     if isinstance(bv_config, dict):
         bv_enabled = bv_config.get("enabled", True)
 
+    bv_web_override = None
+    if isinstance(bv_config, dict) and "web_project" in bv_config:
+        bv_web_override = bv_config["web_project"]
+
+    bv_hint = ""
+
     if not bv_enabled:
         print("Status: SKIP")
         print("Disabled in config.json")
         record("SKIP", "Browser Verification")
+    elif bv_web_override is False:
+        is_web = False
+        print("Status: SKIP")
+        print("web_project: false in config.json")
+        record("SKIP", "Browser Verification")
     else:
-        is_web, web_signal = _detect_web_project(git_root)
+        if bv_web_override is True:
+            is_web, web_signal = True, "config override"
+        else:
+            is_web, web_signal = _detect_web_project(git_root)
+
         if not is_web:
+            bv_hint = "Tip: If this is a web project, run /ms:config to enable browser verification."
             print("Status: SKIP")
             print(f"Not a web project ({web_signal})")
+            print(bv_hint)
             record("SKIP", "Browser Verification")
         else:
             bv_missing: list[str] = []
@@ -1243,6 +1398,8 @@ def cmd_doctor_scan(args: argparse.Namespace) -> None:
     elif not is_web:
         print("Status: SKIP")
         print(f"Not a web project ({web_signal})")
+        if bv_hint:
+            print(bv_hint)
         record("SKIP", "Screenshot Optimization")
     else:
         if shutil.which("cwebp"):
@@ -3643,6 +3800,10 @@ def build_parser() -> argparse.ArgumentParser:
     p = subparsers.add_parser("browser-check", help="Check browser verification prerequisites")
     p.set_defaults(func=cmd_browser_check)
 
+    # --- detect-web ---
+    p = subparsers.add_parser("detect-web", help="Detect if project is a web project")
+    p.set_defaults(func=cmd_detect_web)
+
     # --- doctor-scan ---
     p = subparsers.add_parser("doctor-scan", help="Diagnostic scan of .planning/ tree")
     p.set_defaults(func=cmd_doctor_scan)

package/mindsystem/workflows/transition.md

@@ -1,460 +0,0 @@
-<required_reading>
-
-**Read these files NOW:**
-
-1. `.planning/STATE.md`
-2. `.planning/PROJECT.md`
-3. `.planning/ROADMAP.md`
-4. Current phase's plan files (`*-PLAN.md`)
-5. Current phase's summary files (`*-SUMMARY.md`)
-
-</required_reading>
-
-<purpose>
-
-Mark current phase complete and advance to next. This is the natural point where progress tracking and PROJECT.md evolution happen.
-
-"Planning next phase" = "current phase is done"
-
-</purpose>
-
-<process>
-
-<step name="load_project_state" priority="first">
-
-Before transition, read project state:
-
-```bash
-cat .planning/STATE.md 2>/dev/null
-cat .planning/PROJECT.md 2>/dev/null
-```
-
-Parse current position to verify we're transitioning the right phase.
-Note accumulated context that may need updating after transition.
-
-</step>
-
-<step name="verify_completion">
-
-Check current phase has all plan summaries:
-
-```bash
-ls .planning/phases/XX-current/*-PLAN.md 2>/dev/null | sort
-ls .planning/phases/XX-current/*-SUMMARY.md 2>/dev/null | sort
-```
-
-**Verification logic:**
-
-- Count PLAN files
-- Count SUMMARY files
-- If counts match: all plans complete
-- If counts don't match: incomplete
-
-**If all plans complete:**
-
-```
-⚡ Auto-approved: Transition Phase [X] → Phase [X+1]
-Phase [X] complete — all [Y] plans finished.
-
-Proceeding to mark done and advance...
-```
-
-Proceed directly to cleanup_handoff step.
-
-**If plans incomplete:**
-
-**SAFETY RAIL: Skipping incomplete plans is destructive — always confirm.**
-
-Present:
-
-```
-Phase [X] has incomplete plans:
-- {phase}-01-SUMMARY.md ✓ Complete
-- {phase}-02-SUMMARY.md ✗ Missing
-- {phase}-03-SUMMARY.md ✗ Missing
-
-⚠️ Safety rail: Skipping plans requires confirmation (destructive action)
-
-Options:
-1. Continue current phase (execute remaining plans)
-2. Mark complete anyway (skip remaining plans)
-3. Review what's left
-```
-
-Wait for user decision.
-
-</step>
-
-<step name="update_roadmap">
-
-Update the roadmap file:
-
-```bash
-ROADMAP_FILE=".planning/ROADMAP.md"
-```
-
-Update the file:
-
-- Mark current phase: `[x] Complete`
-- Add completion date
-- Update Progress table
-- Keep next phase as `[ ] Not started`
-
-**Example:**
-
-```markdown
-## Phases
-
-- [x] Phase 1: Foundation (completed 2025-01-15)
-- [ ] Phase 2: Authentication ← Next
-- [ ] Phase 3: Core Features
-
-## Progress
-
-| Phase             | Status      | Completed  |
-| ----------------- | ----------- | ---------- |
-| 1. Foundation     | Complete    | 2025-01-15 |
-| 2. Authentication | Not started | -          |
-| 3. Core Features  | Not started | -          |
-```
-
-</step>
-
-<step name="archive_prompts">
-
-If prompts were generated for the phase, they stay in place.
-The `completed/` subfolder pattern from create-meta-prompts handles archival.
-
-</step>
-
-<step name="evolve_project">
-
-Evolve PROJECT.md to reflect learnings from completed phase.
-
-**Read phase summaries:**
-
-```bash
-cat .planning/phases/XX-current/*-SUMMARY.md
-```
-
-**Assess requirement changes:**
-
-1. **Requirements validated?**
-   - Any requirements shipped in this phase?
-   - Add to Validated with phase reference: `- ✓ [Requirement] — Phase X`
-
-2. **Requirements invalidated?**
-   - Any requirements discovered to be unnecessary or wrong?
-   - Add to Out of Scope with reason: `- [Requirement] — [why invalidated]`
-
-3. **Business context evolved?**
-   - Has understanding of audience, problem, or differentiation changed?
-   - Update Who It's For, Core Problem, or How It's Different if so
-   - New key flows emerged? → Update Key User Flows
-
-4. **Decisions to log?**
-   - Extract decisions from SUMMARY.md files
-   - Add to Key Decisions table with outcome if known
-
-5. **"What This Is" still accurate?**
-   - If the product has meaningfully changed, update the description
-   - Keep it current and accurate
-
-**Update PROJECT.md:**
-
-Make the edits inline. Update "Last updated" footer:
-
-```markdown
----
-*Last updated: [date] after Phase [X]*
-```
-
-**Example evolution:**
-
-Before:
-
-```markdown
-## Validated
-
-- ✓ Canvas drawing tools — Phase 1
-
-## Out of Scope
-
-- OAuth2 — complexity not needed for v1
-```
-
-After (Phase 2 shipped JWT auth, discovered rate limiting needed):
-
-```markdown
-## Validated
-
-- ✓ Canvas drawing tools — Phase 1
-- ✓ JWT authentication — Phase 2
-
-## Out of Scope
-
-- OAuth2 — complexity not needed for v1
-- Offline mode — real-time is core value, discovered Phase 2
-```
-
-**Step complete when:**
-
-- [ ] Phase summaries reviewed for learnings
-- [ ] Shipped requirements added to Validated
-- [ ] Invalidated requirements added to Out of Scope with reason
-- [ ] Business context sections reviewed (Who It's For, Core Problem, How It's Different, Key User Flows)
-- [ ] New decisions logged with rationale
-- [ ] "What This Is" updated if product changed
-- [ ] "Last updated" footer reflects this transition
-
-</step>
-
-<step name="update_current_position_after_transition">
-
-Update Current Position section in STATE.md to reflect phase completion and transition.
-
-**Format:**
-
-```markdown
-Phase: [next] of [total] ([Next phase name])
-Plan: Not started
-Status: Ready to plan
-Last activity: [today] — Phase [X] complete, transitioned to Phase [X+1]
-
-Progress: [updated progress bar]
-```
-
-**Instructions:**
-
-- Increment phase number to next phase
-- Reset plan to "Not started"
-- Set status to "Ready to plan"
-- Update last activity to describe transition
-- Recalculate progress bar based on completed plans
-
-**Example — transitioning from Phase 2 to Phase 3:**
-
-Before:
-
-```markdown
-## Current Position
-
-Phase: 2 of 4 (Authentication)
-Plan: 2 of 2 in current phase
-Status: Phase complete
-Last activity: 2025-01-20 — Completed 02-02-PLAN.md
-
-Progress: ███████░░░ 60%
-```
-
-After:
-
-```markdown
-## Current Position
-
-Phase: 3 of 4 (Core Features)
-Plan: Not started
-Status: Ready to plan
-Last activity: 2025-01-20 — Phase 2 complete, transitioned to Phase 3
-
-Progress: ███████░░░ 60%
-```
-
-**Step complete when:**
-
-- [ ] Phase number incremented to next phase
-- [ ] Plan status reset to "Not started"
-- [ ] Status shows "Ready to plan"
-- [ ] Last activity describes the transition
-- [ ] Progress bar reflects total completed plans
-
-</step>
-
-<step name="update_project_reference">
-
-Update Project Reference section in STATE.md.
-
-```markdown
-## Project Reference
-
-See: .planning/PROJECT.md (updated [today])
-
-**Core value:** [Current core value from PROJECT.md]
-**Current focus:** [Next phase name]
-```
-
-Update the date and current focus to reflect the transition.
-
-</step>
-
-<step name="review_accumulated_context">
-
-Review and update Accumulated Context section in STATE.md.
-
-**Decisions:**
-
-- Note recent decisions from this phase (3-5 max)
-- Full log lives in PROJECT.md Key Decisions table
-
-**Blockers/Concerns:**
-
-- Review blockers from completed phase
-- If addressed in this phase: Remove from list
-- If still relevant for future: Keep with "Phase X" prefix
-- Add any new concerns from completed phase's summaries
-
-**Example:**
-
-Before:
-
-```markdown
-### Blockers/Concerns
-
-- ⚠️ [Phase 1] Database schema not indexed for common queries
-- ⚠️ [Phase 2] WebSocket reconnection behavior on flaky networks unknown
-```
-
-After (if database indexing was addressed in Phase 2):
-
-```markdown
-### Blockers/Concerns
-
-- ⚠️ [Phase 2] WebSocket reconnection behavior on flaky networks unknown
-```
-
-**Step complete when:**
-
-- [ ] Recent decisions noted (full log in PROJECT.md)
-- [ ] Resolved blockers removed from list
-- [ ] Unresolved blockers kept with phase prefix
-- [ ] New concerns from completed phase added
-
-</step>
-
-<step name="update_session_continuity_after_transition">
-
-Update Session Continuity section in STATE.md to reflect transition completion.
-
-**Format:**
-
-```markdown
-Last session: [today]
-Stopped at: Phase [X] complete, ready to plan Phase [X+1]
-```
-
-**Step complete when:**
-
-- [ ] Last session timestamp updated to current date and time
-- [ ] Stopped at describes phase completion and next phase
-
-</step>
-
-<step name="offer_next_phase">
-
-**MANDATORY: Verify milestone status before presenting next steps.**
-
-**Step 1: Read ROADMAP.md and identify phases in current milestone**
-
-Read the ROADMAP.md file and extract:
-1. Current phase number (the phase just transitioned from)
-2. All phase numbers in the current milestone section
-
-To find phases, look for:
-- Phase headers: lines starting with `### Phase` or `#### Phase`
-- Phase list items: lines like `- [ ] **Phase X:` or `- [x] **Phase X:`
-
-Count total phases and identify the highest phase number in the milestone.
-
-State: "Current phase is {X}. Milestone has {N} phases (highest: {Y})."
-
-**Step 2: Route based on milestone status**
-
-| Condition | Meaning | Action |
-|-----------|---------|--------|
-| current phase < highest phase | More phases remain | Go to **Route A** |
-| current phase = highest phase | Milestone complete | Go to **Route B** |
-
----
-
-**Route A: More phases remain in milestone**
-
-Read ROADMAP.md to get the next phase's name and goal.
-
-**If next phase exists:**
-
-```
-Phase [X] marked complete.
-
-Next: Phase [X+1] — [Name]
-
-⚡ Auto-continuing: Plan Phase [X+1] in detail
-```
-
-Exit skill and invoke SlashCommand("/ms:plan-phase [X+1]")
-
----
-
-**Route B: Milestone complete (all phases done)**
-
-```
-Phase {X} marked complete.
-
-🎉 Milestone is 100% complete — all {N} phases finished!
-
-⚡ Auto-continuing: Complete milestone and archive
-```
-
-Exit skill and invoke SlashCommand("/ms:complete-milestone")
-
-</step>
-
-</process>
-
-<implicit_tracking>
-
-Progress tracking is IMPLICIT:
-
-- "Plan phase 2" → Phase 1 must be done (or ask)
-- "Plan phase 3" → Phases 1-2 must be done (or ask)
-- Transition workflow makes it explicit in ROADMAP.md
-
-No separate "update progress" step. Forward motion IS progress.
-
-</implicit_tracking>
-
-<partial_completion>
-
-If user wants to move on but phase isn't fully complete:
-
-```
-Phase [X] has incomplete plans:
-- {phase}-02-PLAN.md (not executed)
-- {phase}-03-PLAN.md (not executed)
-
-Options:
-1. Mark complete anyway (plans weren't needed)
-2. Defer work to later phase
-3. Stay and finish current phase
-```
-
-Respect user judgment — they know if work matters.
-
-**If marking complete with incomplete plans:**
-
-- Note in transition message which plans were skipped
-
-</partial_completion>
-
-<success_criteria>
-
-Transition is complete when:
-
-- [ ] Current phase plan summaries verified (all exist or user chose to skip)
-- [ ] Any stale handoffs deleted
-- [ ] ROADMAP.md updated with completion status
-- [ ] PROJECT.md evolved (requirements, decisions, description if needed)
-- [ ] STATE.md updated (position, project reference, context, session)
-- [ ] Progress table updated
-- [ ] User knows next steps
-
-</success_criteria>