mindsystem-cc 4.4.0 → 4.4.1

package/README.md

@@ -2,21 +2,43 @@
 
 ![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
+
+- **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 +109,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 +299,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 +323,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 +350,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 +525,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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mindsystem-cc",
-  "version": "4.4.0",
+  "version": "4.4.1",
   "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)