@devobsessed/code-captain 0.3.0 → 0.3.3

package/bin/install.js

@@ -444,6 +444,16 @@ class CodeCaptainInstaller {
     return recommendations;
   }
 
+  // Detect .sln files in the current directory
+  async detectSlnFiles() {
+    try {
+      const entries = await fs.readdir(".");
+      return entries.filter((entry) => entry.endsWith(".sln"));
+    } catch {
+      return [];
+    }
+  }
+
   // Auto-detect IDE preference
   detectIDE() {
     const detections = [];
@@ -527,9 +537,33 @@ class CodeCaptainInstaller {
     const changeInfo = await this.detectChanges(selectedIDE);
 
     if (changeInfo.isFirstInstall) {
-      // Fresh installation - install everything
+      // Fresh installation - install everything, but check for VS Solution View opt-in
+      let installVsSolution = false;
+      if (selectedIDE === "copilot") {
+        // Auto-detect .sln files to determine if VS Solution View is relevant
+        const slnFiles = await this.detectSlnFiles();
+        if (slnFiles.length > 0) {
+          console.log(
+            chalk.green(
+              `\n✨ Detected .NET solution file(s): ${slnFiles.join(", ")}`
+            )
+          );
+          const { enableVsSolution } = await inquirer.prompt([
+            {
+              type: "confirm",
+              name: "enableVsSolution",
+              message:
+                "Install VS Solution View (Directory.Build.props) to make Code Captain files visible in Visual Studio Solution Explorer?",
+              default: true,
+            },
+          ]);
+          installVsSolution = enableVsSolution;
+        }
+      }
+
       return {
         installAll: true,
+        installVsSolution,
         changeInfo,
       };
     }
@@ -1111,13 +1145,15 @@ class CodeCaptainInstaller {
         spinner.text = `Installing files... (${completed}/${files.length})`;
       }
 
-      // Handle Directory.Build.props for vs-solution component (opt-in only, not in installAll)
+      // Handle Directory.Build.props for vs-solution component
       let vsSolutionResult = null;
-      if (
-        !installOptions.installAll &&
-        selectedComponents &&
-        selectedComponents.includes("vs-solution")
-      ) {
+      const shouldInstallVsSolution =
+        (installOptions.installAll && installOptions.installVsSolution) ||
+        (!installOptions.installAll &&
+          selectedComponents &&
+          selectedComponents.includes("vs-solution"));
+
+      if (shouldInstallVsSolution) {
         spinner.text = "Installing Directory.Build.props...";
         vsSolutionResult = await this.installDirectoryBuildProps();
       }

package/copilot/Directory.Build.props

@@ -1,8 +1,10 @@
 <Project>
-  <!-- Code Captain: Make .github/ Copilot files visible in VS Solution Explorer -->
+  <!-- Code Captain: Make Copilot and Code Captain files visible in VS Solution Explorer -->
   <ItemGroup Label="Code Captain">
-    <None Include=".github\copilot-instructions.md" Link="Code Captain\copilot-instructions.md" />
-    <None Include=".github\agents\**\*" Link="Code Captain\agents\%(RecursiveDir)%(Filename)%(Extension)" />
-    <None Include=".github\prompts\**\*" Link="Code Captain\prompts\%(RecursiveDir)%(Filename)%(Extension)" />
+    <None Include="$(MSBuildThisFileDirectory).github\copilot-instructions.md" Link="Code Captain\copilot-instructions.md" />
+    <None Include="$(MSBuildThisFileDirectory).github\agents\**\*" Link="Code Captain\agents\%(RecursiveDir)%(Filename)%(Extension)" />
+    <None Include="$(MSBuildThisFileDirectory).github\prompts\**\*" Link="Code Captain\prompts\%(RecursiveDir)%(Filename)%(Extension)" />
+    <None Include="$(MSBuildThisFileDirectory).code-captain\docs\**\*" Link="Code Captain\docs\%(RecursiveDir)%(Filename)%(Extension)" />
+    <None Include="$(MSBuildThisFileDirectory).code-captain\specs\**\*" Link="Code Captain\specs\%(RecursiveDir)%(Filename)%(Extension)" />
   </ItemGroup>
 </Project>

package/copilot/copilot-instructions.md

@@ -17,8 +17,34 @@ When a user invokes any Code Captain command, you MUST:
    - "Steady as she goes! Code Captain prepared to steer your project to success."
    - "Anchors aweigh! Code Captain ready to lead your development expedition."
    - "All hands on deck! Code Captain here to guide your coding voyage."
-2. **Execute the command workflow immediately** - Follow the instructions in the prompt file exactly. Do NOT describe or summarize the instructions back to the user. Act on them.
-3. **Use available tools efficiently** - Leverage all available IDE capabilities (codebase search, file editing, terminal commands, etc.)
+2. **Locate the repository root (mandatory)** - Before accessing any `.code-captain/` path or executing any command workflow, confirm you are at the repository root. See **Working Directory Bootstrap** below.
+3. **Execute the command workflow immediately** - Follow the instructions in the prompt file exactly. Do NOT describe or summarize the instructions back to the user. Act on them.
+4. **Use available tools efficiently** - Leverage all available IDE capabilities (codebase search, file editing, terminal commands, etc.)
+
+## Working Directory Bootstrap
+
+IDEs may open the terminal in a sub-project directory instead of the repository root (common with Visual Studio + .NET solutions). The `.code-captain/` folder lives at the repo root, so you MUST locate it before any file access or terminal command that references `.code-captain/`.
+
+**Detection steps (run once at the start of every command):**
+
+1. **Prefer tool-based search (no shell dependency)** — Use `codebase` or `search` to look for `.code-captain/` or `.git/`. These tools work regardless of shell type or OS. If the repo root is found this way, record the path and skip to step 5.
+2. **If terminal fallback is needed, detect the shell first** — Run this single command via `runCommands`:
+   ```
+   echo $PSVersionTable
+   ```
+   - If the output contains version info (e.g., `PSVersion`), the shell is **PowerShell** (typical: Windows + Visual Studio).
+   - If the output is blank or errors, the shell is **bash/zsh** (typical: macOS, Linux, VS Code on any OS).
+   - **Record the detected shell type** and use only the matching syntax for all subsequent commands in this session.
+3. **Check for `.code-captain/` in the current directory:**
+   - **PowerShell:** `if (Test-Path .code-captain) { 'FOUND' } else { 'NOT_FOUND' }`
+   - **Bash/Zsh:** `test -d .code-captain && echo FOUND || echo NOT_FOUND`
+4. If `NOT_FOUND`, navigate to the parent directory and check again. Repeat up to 3 levels:
+   - **PowerShell:** `Set-Location .. ; if (Test-Path .code-captain) { Get-Location } else { 'NOT_FOUND' }`
+   - **Bash/Zsh:** `cd .. && test -d .code-captain && pwd || echo NOT_FOUND`
+5. Once the root is found, **record the repo root path** and prefix all `.code-captain/` references with that path for the remainder of the session.
+6. If `.code-captain/` is not found after 3 levels, inform the user: "Could not locate the .code-captain directory. Please ensure you opened the repository root folder in your IDE, or run `/initialize` to create the project foundation."
+
+**Important:** Do NOT skip this step even if you assume you are at the root. The one-time cost of verification prevents repeated failures and retries.
 
 ## File Organization
 
@@ -65,15 +91,22 @@ When executing terminal commands via `runCommands`:
 3. **CWD preservation** — Use single-expression commands when working in subdirectories: `cd <subdir> && <command>`. Never leave the terminal in a shifted working directory. All `.code-captain/` paths are relative to the repository root.
 4. **Quick verification** — Prefer non-blocking checks over full builds. Use `--dry-run`, `--no-restore`, or type-check-only flags when assessing project health.
 5. **Verify before using npm scripts** — If a `package.json` `test` or `build` script exists, check its contents before running it. Scripts may invoke watch mode or dev servers.
+6. **Detect the shell before running commands** — The shell type varies by IDE and OS. The Working Directory Bootstrap detects this once per session. Use the detected shell type for all commands:
+   - **Windows + Visual Studio:** Typically PowerShell. Uses `Test-Path`, `Set-Location`, `Get-ChildItem`, and `;` to chain statements.
+   - **macOS / Linux (any IDE):** Typically zsh or bash. Uses `test -d`, `cd`, `ls`, and `&&` to chain statements. PowerShell is NOT available unless explicitly installed.
+   - **Windows + VS Code:** Usually PowerShell, but may be configured to use Git Bash, WSL, or CMD.
+   - **Path separators:** Always use `/` (forward slash) — it works in PowerShell, bash, and zsh.
+   - **When in doubt:** Prefer tool-based operations (`codebase`, `search`, `editFiles`) over terminal commands. Tools are shell-independent.
 
 ## Monorepo & Solution Awareness
 
 Projects may contain multiple sub-projects (e.g., .NET solutions with React frontends). When working in these projects:
 
-1. **Detect project topology early** — Look for `.sln` files, multiple `package.json` files, or workspace configurations (`pnpm-workspace.yaml`, `lerna.json`, `nx.json`). This tells you the project has subdirectories with independent tooling.
-2. **Identify the target subdirectory** — Determine which sub-project contains the code relevant to the current task. Note its path relative to the repo root.
-3. **Root-relative file references** — All `.code-captain/` paths (specs, progress trackers, docs) are relative to the repository root, not any subdirectory. After running commands in a subdirectory, verify the working directory before referencing `.code-captain/` paths.
-4. **Subdirectory-specific tooling** — Each sub-project may have its own `package.json`, test runner, build tool, and configuration. Don't assume the root-level tooling applies to subdirectories.
+1. **Repo root is already known** — The Working Directory Bootstrap (above) has already located the repo root. Use that recorded path for all `.code-captain/` references.
+2. **Detect project topology early** — Look for `.sln` files, multiple `package.json` files, or workspace configurations (`pnpm-workspace.yaml`, `lerna.json`, `nx.json`). This tells you the project has subdirectories with independent tooling.
+3. **Identify the target subdirectory** — Determine which sub-project contains the code relevant to the current task. Note its path relative to the repo root.
+4. **Root-relative file references** — All `.code-captain/` paths (specs, progress trackers, docs) are relative to the repository root, not any subdirectory. When running terminal commands in a subdirectory, always return to or reference the repo root path for `.code-captain/` operations.
+5. **Subdirectory-specific tooling** — Each sub-project may have its own `package.json`, test runner, build tool, and configuration. Don't assume the root-level tooling applies to subdirectories.
 
 ## Behavioral Rules
 

package/copilot/prompts/create-spec.prompt.md

@@ -11,12 +11,36 @@ Your mission: Turn the user's rough feature idea into a clear work specification
 
 ### Phase 1: Contract Establishment (No File Creation)
 
+#### Step 1.0: Pre-flight Check
+
+Before starting, verify these foundational files exist in `.code-captain/docs/`:
+
+- `tech-stack.md`
+- `code-style.md`
+- `objective.md`
+
+If **ANY** of these files are missing, inform the user before proceeding:
+
+```text
+I notice this project hasn't been fully initialized — the foundational docs
+(tech-stack, code-style, objective) are missing from .code-captain/docs/.
+Running /initialize first will produce better specification results because
+I'll have your project's architecture, conventions, and patterns as context.
+
+Would you like to:
+1. Switch to /initialize now (recommended)
+2. Continue with /create-spec without the foundational context
+```
+
+If the user chooses option 2, proceed but note that pattern detection will rely entirely on live codebase scanning rather than pre-analyzed documentation.
+
 #### Step 1.1: Initial Context Scan
 
 - Scan existing `.code-captain/specs/` for related specifications
 - Analyze current codebase architecture and patterns using `codebase`
-- Load project context files (`tech-stack.md`, `code-style.md`, `objective.md`)
-- **Output:** Context summary (no files created yet)
+- Load project context files if they exist (`tech-stack.md`, `code-style.md`, `objective.md`)
+- **Identify existing codebase patterns** — Catalog naming conventions, project structure patterns, architectural layers (e.g., repository/service/controller), dependency injection patterns, and any established conventions. These become automatic constraints for the specification.
+- **Output:** Context summary including detected patterns (no files created yet)
 
 #### Step 1.2: Gap Analysis & Silent Enumeration
 
@@ -85,7 +109,7 @@ When confident, present a contract proposal with any concerns surfaced:
 
 **Format:**
 
-```
+```text
 ## Specification Contract
 
 **Deliverable:** [One clear sentence describing what will be built]
@@ -104,6 +128,11 @@ When confident, present a contract proposal with any concerns surfaced:
 - [Specific concern about feasibility, performance, or architecture]
 - [Suggested alternative or mitigation approach]
 
+**Existing Patterns to Follow:**
+- [Patterns detected from codebase scan or code-style.md — e.g., repository pattern, service layer, naming conventions]
+- [Architectural layers and their relationships]
+- [Any relevant conventions that new code must adhere to]
+
 **Recommendations:**
 - [Suggestions for improving the approach based on codebase analysis]
 - [Ways to reduce risk or complexity]
@@ -132,7 +161,7 @@ This returns the current date in `YYYY-MM-DD` format for folder naming:
 
 **Generated folder (using determined date):**
 
-```
+```text
 .code-captain/specs/[DATE]-{feature-name}/
 ├── spec.md                    # Main specification (from contract)
 ├── spec-lite.md              # Condensed version for AI context
@@ -273,7 +302,7 @@ Each user story gets its own file for better organization. Keep implementation t
 
 Present complete package with file references:
 
-```
+```text
 Specification package created successfully!
 
 .code-captain/specs/[DATE]-feature-name/
@@ -302,9 +331,19 @@ Please read through the files and let me know:
 - Are the user stories appropriately sized (5-7 tasks each)?
 - Should any stories be split further or combined?
 
-Once you're satisfied with the specification, I can help you start implementation with the first story, or we can make any needed adjustments.
+Once you're satisfied with the specification, you can start implementation using /execute-task, or we can make any needed adjustments.
 ```
 
+## CRITICAL: Command Boundary — STOP HERE
+
+**This command ENDS after presenting the spec package review above.**
+
+- **DO NOT** proceed to implement any code from the stories.
+- **DO NOT** begin executing tasks, writing tests, or making code changes.
+- **DO NOT** offer to "get started on the first story" and then begin coding.
+- Your ONLY job is to create the specification documents. Implementation is handled by the `/execute-task` command.
+- After presenting the final review, **STOP and wait for the user's response.**
+
 ## Tool Integration
 
 **Primary tools:**
@@ -323,7 +362,7 @@ Once you're satisfied with the specification, I can help you start implementatio
 
 ## Example of expected interaction
 
-```
+```text
 Developer: /create-spec "real-time multiplayer chat with blockchain integration"
 
 Agent: I'm ready to help you create a comprehensive specification.

package/copilot/prompts/execute-task.prompt.md

@@ -169,6 +169,17 @@ For each implementation task within the story:
 
 **STORY CANNOT BE MARKED COMPLETE WITH ANY FAILING TESTS**
 
+### CRITICAL: One Story at a Time
+
+**Execute ONLY the single selected story per invocation of this command.**
+
+- After completing Step 4 (all tasks within the story) and verifying tests pass, proceed to Step 5.
+- After Step 5, **STOP execution completely.**
+- **DO NOT** automatically begin the next story.
+- **DO NOT** ask "shall I continue with story 2?" and then start coding before the user responds.
+- Present the completion summary and **wait for the user** to explicitly request the next story.
+- The user must invoke `/execute-task` again or explicitly ask to continue with the next story.
+
 ### Step 5: Story Completion & Status Updates
 
 Update story file status and progress tracking files with completion details, ensuring all tests pass before marking complete.
@@ -194,3 +205,24 @@ Update story file status and progress tracking files with completion details, en
 - File-based progress tracking in `.code-captain/current-task-progress.md`
 - Story status updates in specification files
 - Test execution results documentation with pass/fail counts
+
+## CRITICAL: Command Boundary — STOP After Story Completion
+
+After completing a story and updating status files, present a summary in this format:
+
+```
+Story [N]: [Title] — COMPLETED
+
+Results:
+- Tests: [X] passed, [Y] failed
+- Tasks completed: [N/N]
+- Acceptance criteria: [all met / details]
+
+Updated files:
+- [list of modified/created files]
+
+Next available story: Story [N+1]: [Title]
+To continue, invoke /execute-task again or ask me to proceed with the next story.
+```
+
+**STOP here. Do NOT begin the next story automatically.**

package/cursor/commands/create-spec.md

@@ -12,12 +12,36 @@ Generate comprehensive feature specifications using a contract-first approach th
 
 > Your goal is to turn my rough feature idea into a very clear work specification. You will deliver the complete spec package only after we both agree on the requirements contract. **Important: Challenge ideas that don't make technical or business sense - it's better to surface concerns early than build the wrong thing.**
 
+#### Step 1.0: Pre-flight Check
+
+Before starting, verify these foundational files exist in `.code-captain/docs/`:
+
+- `tech-stack.md`
+- `code-style.md`
+- `objective.md`
+
+If **ANY** of these files are missing, inform the user before proceeding:
+
+```text
+I notice this project hasn't been fully initialized — the foundational docs
+(tech-stack, code-style, objective) are missing from .code-captain/docs/.
+Running /initialize first will produce better specification results because
+I'll have your project's architecture, conventions, and patterns as context.
+
+Would you like to:
+1. Switch to /initialize now (recommended)
+2. Continue with /create-spec without the foundational context
+```
+
+If the user chooses option 2, proceed but note that pattern detection will rely entirely on live codebase scanning rather than pre-analyzed documentation.
+
 #### Step 1.1: Initial Context Scan
 
 - Scan existing `.code-captain/specs/` for related specifications
 - Analyze current codebase architecture and patterns using `codebase_search`
-- Load project context files (`tech-stack.md`, `code-style.md`, `objective.md`)
-- **Output:** Context summary (no files created yet)
+- Load project context files if they exist (`tech-stack.md`, `code-style.md`, `objective.md`)
+- **Identify existing codebase patterns** — Catalog naming conventions, project structure patterns, architectural layers (e.g., repository/service/controller), dependency injection patterns, and any established conventions. These become automatic constraints for the specification.
+- **Output:** Context summary including detected patterns (no files created yet)
 
 #### Step 1.2: Gap Analysis & Silent Enumeration
 
@@ -86,7 +110,7 @@ When confident, present a contract proposal with any concerns surfaced:
 
 **Format:**
 
-```
+```text
 ## Specification Contract
 
 **Deliverable:** [One clear sentence describing what will be built]
@@ -105,6 +129,11 @@ When confident, present a contract proposal with any concerns surfaced:
 - [Specific concern about feasibility, performance, or architecture]
 - [Suggested alternative or mitigation approach]
 
+**Existing Patterns to Follow:**
+- [Patterns detected from codebase scan or code-style.md — e.g., repository pattern, service layer, naming conventions]
+- [Architectural layers and their relationships]
+- [Any relevant conventions that new code must adhere to]
+
 **💡 Recommendations:**
 - [Suggestions for improving the approach based on codebase analysis]
 - [Ways to reduce risk or complexity]
@@ -124,7 +153,7 @@ Options:
 
 #### Step 2.1: Initialize Tracking
 
-```bash
+```text
 # Use todo_write to track creation process
 1. Get current date and create spec folder structure
 2. Generate core specification document
@@ -145,7 +174,7 @@ This returns the current date in `YYYY-MM-DD` format for folder naming:
 
 **Generated folder (using determined date):**
 
-```
+```text
 .code-captain/specs/[DATE]-{feature-name}/
 ├── spec.md                    # Main specification (from contract)
 ├── spec-lite.md              # Condensed version for AI context
@@ -311,7 +340,7 @@ This returns the current date in `YYYY-MM-DD` format for folder naming:
 
 Present complete package with file references:
 
-```
+```text
 ✅ Specification package created successfully!
 
 📁 .code-captain/specs/[DATE]-feature-name/
@@ -347,9 +376,19 @@ The user-stories folder structure allows you to:
 - Assign different stories to different team members
 - Keep task lists manageable and actionable
 
-Once you're satisfied with the specification, I can help you start implementation with the first story, or we can make any needed adjustments.
+Once you're satisfied with the specification, you can start implementation using /execute-task, or we can make any needed adjustments.
 ```
 
+## CRITICAL: Command Boundary — STOP HERE
+
+**This command ENDS after presenting the spec package review above.**
+
+- **DO NOT** proceed to implement any code from the stories.
+- **DO NOT** begin executing tasks, writing tests, or making code changes.
+- **DO NOT** offer to "get started on the first story" and then begin coding.
+- Your ONLY job is to create the specification documents. Implementation is handled by the `/execute-task` command.
+- After presenting the final review, **STOP and wait for the user's response.**
+
 ## Key Improvements Over Original
 
 ### 1. Contract-First Approach
@@ -379,7 +418,7 @@ Once you're satisfied with the specification, I can help you start implementatio
 
 ## Example Usage Flow
 
-```
+```text
 Developer: /create-spec "real-time multiplayer chat with blockchain integration"
 
 Agent: I'm ready to help you create a comprehensive specification.

package/cursor/commands/execute-task.md

@@ -285,6 +285,17 @@ Use available testing tools to verify:
 4. Repeat until NO tests fail
 5. Only then mark story as complete
 
+### CRITICAL: One Story at a Time
+
+**Execute ONLY the single selected story per invocation of this command.**
+
+- After completing Step 6 (test validation) and verifying tests pass, proceed to Step 7.
+- After Step 7, **STOP execution completely.**
+- **DO NOT** automatically begin the next story.
+- **DO NOT** ask "shall I continue with story 2?" and then start coding before the user responds.
+- Present the completion summary and **wait for the user** to explicitly request the next story.
+- The user must invoke `/execute-task` again or explicitly ask to continue with the next story.
+
 ### Step 7: Story Completion & Status Updates
 
 **Update story file status:**
@@ -367,9 +378,11 @@ Next available stories:
 - Story 2: Password Reset (4 tasks) - Not Started
 - Story 3: Profile Management (6 tasks) - Not Started
 
-Would you like to proceed with the next story?
+To continue, invoke /execute-task again or ask me to proceed with the next story.
 ```
 
+**STOP here. Do NOT begin the next story automatically.**
+
 **If ANY tests fail, present this instead:**
 
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devobsessed/code-captain",
-  "version": "0.3.0",
+  "version": "0.3.3",
   "description": "Unified AI Development Agent System with intelligent change detection",
   "type": "module",
   "bin": {