@devobsessed/code-captain 0.2.0 → 0.2.2

package/bin/install.js

@@ -37,9 +37,10 @@ class CodeCaptainInstaller {
       },
       copilot: {
         name: "Copilot",
-        description: "Visual Studio Code with Copilot extension",
+        description:
+          "VS Code or Visual Studio with GitHub Copilot",
         details:
-          "Uses .github/agents/ + .github/prompts/ + .code-captain/docs/",
+          "Uses .github/copilot-instructions.md + .github/agents/ + .github/prompts/ + .code-captain/docs/",
       },
       claude: {
         name: "Claude Code",
@@ -125,7 +126,11 @@ class CodeCaptainInstaller {
         ".cursor/rules/cc.mdc",
         ".cursor/rules/",
       ],
-      "Copilot Integration": [".github/agents/", ".github/prompts/"],
+      "Copilot Integration": [
+        ".github/copilot-instructions.md",
+        ".github/agents/",
+        ".github/prompts/",
+      ],
       "Claude Integration": [
         ".code-captain/claude/",
         "claude-code/",
@@ -679,8 +684,18 @@ class CodeCaptainInstaller {
       case "copilot":
         return [
           ...baseChoices,
+          {
+            name: "Copilot Instructions (.github/copilot-instructions.md)",
+            value: "instructions",
+            checked: true,
+          },
           { name: "Copilot Agents", value: "agents", checked: true },
           { name: "Copilot Prompts", value: "prompts", checked: true },
+          {
+            name: "VS Solution View (Directory.Build.props)",
+            value: "vs-solution",
+            checked: false,
+          },
         ];
 
       case "claude":
@@ -842,6 +857,83 @@ class CodeCaptainInstaller {
     }
   }
 
+  // Install Directory.Build.props with merge support
+  async installDirectoryBuildProps() {
+    const targetPath = "Directory.Build.props";
+    const templateSource = "copilot/Directory.Build.props";
+    const marker = 'Label="Code Captain"';
+
+    // Read template content
+    let templateContent;
+    if (this.config.localSource) {
+      const localPath = path.join(this.config.localSource, templateSource);
+      if (!(await fs.pathExists(localPath))) {
+        throw new Error(`Template not found: ${localPath}`);
+      }
+      templateContent = await fs.readFile(localPath, "utf8");
+    } else {
+      const url = `${this.config.baseUrl}/${templateSource}`;
+      const response = await this.fetchWithTimeout(url, {}, 20000);
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+      }
+      templateContent = await response.text();
+    }
+
+    // Extract the ItemGroup block from template
+    const itemGroupMatch = templateContent.match(
+      /[ \t]*<ItemGroup Label="Code Captain">[\s\S]*?<\/ItemGroup>/
+    );
+    if (!itemGroupMatch) {
+      throw new Error("Template missing Code Captain ItemGroup");
+    }
+    const itemGroupBlock = itemGroupMatch[0];
+
+    const exists = await fs.pathExists(targetPath);
+
+    if (!exists) {
+      // Case 1: File doesn't exist — create from template
+      await fs.writeFile(targetPath, templateContent);
+      return { action: "created" };
+    }
+
+    // File exists — read it
+    const existingContent = await fs.readFile(targetPath, "utf8");
+
+    if (existingContent.includes(marker)) {
+      // Case 3: Already has Code Captain content — replace if changed
+      const existingBlock = existingContent.match(
+        /[ \t]*<ItemGroup Label="Code Captain">[\s\S]*?<\/ItemGroup>/
+      );
+      if (existingBlock && existingBlock[0] === itemGroupBlock) {
+        return { action: "up-to-date" };
+      }
+
+      // Replace existing block
+      await fs.copy(targetPath, `${targetPath}.backup`);
+      const updatedContent = existingContent.replace(
+        /[ \t]*<ItemGroup Label="Code Captain">[\s\S]*?<\/ItemGroup>/,
+        itemGroupBlock
+      );
+      await fs.writeFile(targetPath, updatedContent);
+      return { action: "updated" };
+    }
+
+    // Case 2: File exists, no Code Captain content — inject before </Project>
+    await fs.copy(targetPath, `${targetPath}.backup`);
+    if (!existingContent.includes("</Project>")) {
+      throw new Error(
+        "Directory.Build.props is malformed (missing </Project>). Please fix manually."
+      );
+    }
+    const injectedContent = existingContent.replace(
+      /<\/Project>/,
+      `\n${itemGroupBlock}\n</Project>`
+    );
+    await fs.writeFile(targetPath, injectedContent);
+    return { action: "merged" };
+  }
+
   // Get IDE-specific file list
   getIDEFiles(selectedIDE, selectedComponents = null) {
     const files = [];
@@ -897,6 +989,15 @@ class CodeCaptainInstaller {
         break;
 
       case "copilot":
+        // Instructions
+        if (includeAll || selectedComponents.includes("instructions")) {
+          files.push({
+            source: "copilot/copilot-instructions.md",
+            target: ".github/copilot-instructions.md",
+            component: "instructions",
+          });
+        }
+
         // Agents
         if (includeAll || selectedComponents.includes("agents")) {
           files.push({
@@ -1010,6 +1111,17 @@ class CodeCaptainInstaller {
         spinner.text = `Installing files... (${completed}/${files.length})`;
       }
 
+      // Handle Directory.Build.props for vs-solution component (opt-in only, not in installAll)
+      let vsSolutionResult = null;
+      if (
+        !installOptions.installAll &&
+        selectedComponents &&
+        selectedComponents.includes("vs-solution")
+      ) {
+        spinner.text = "Installing Directory.Build.props...";
+        vsSolutionResult = await this.installDirectoryBuildProps();
+      }
+
       spinner.succeed(
         `${this.ides[selectedIDE].name} integration installed successfully!`
       );
@@ -1031,6 +1143,7 @@ class CodeCaptainInstaller {
             installOptions.changeInfo.newFiles.length > 0),
         backupsCreated: backupPaths.length > 0,
         backupPaths: backupPaths,
+        vsSolutionResult,
       };
     } catch (error) {
       spinner.fail("Installation failed");
@@ -1101,21 +1214,32 @@ class CodeCaptainInstaller {
       case "copilot":
         console.log(
           chalk.blue("1.") +
-            " Restart VS Code to load agents from " +
-            chalk.cyan(".github/agents/")
+            " Restart your IDE to load the new files"
+        );
+        console.log(
+          chalk.blue("2.") +
+            " " +
+            chalk.cyan(".github/copilot-instructions.md") +
+            " is automatically included in every Copilot request"
+        );
+        console.log(
+          chalk.bold.yellow("\n   VS Code:")
         );
-        console.log(chalk.blue("2.") + " Open Copilot Chat in VS Code");
         console.log(
           chalk.blue("3.") +
             " Select the " +
             chalk.cyan("Code Captain") +
-            " agent from the agent picker"
+            " agent from the agent picker, or invoke prompts with " +
+            chalk.cyan("/command-name")
+        );
+        console.log(
+          chalk.bold.yellow("\n   Visual Studio:")
         );
         console.log(
           chalk.blue("4.") +
-            " Use prompts from " +
-            chalk.cyan(".github/prompts/") +
-            " for workflows"
+            " Invoke prompts with " +
+            chalk.cyan("#command-name") +
+            " in Copilot Chat (agents are not supported)"
         );
         break;
 
@@ -1143,6 +1267,18 @@ class CodeCaptainInstaller {
         break;
     }
 
+    // Show Directory.Build.props result if applicable
+    if (installResult.vsSolutionResult) {
+      const action = installResult.vsSolutionResult.action;
+      const messages = {
+        created: "Created Directory.Build.props — .github/ files now visible in VS Solution Explorer",
+        merged: "Merged Code Captain items into existing Directory.Build.props (backup saved as .backup)",
+        updated: "Updated Code Captain section in Directory.Build.props (backup saved as .backup)",
+        "up-to-date": "Directory.Build.props is already up to date",
+      };
+      console.log(chalk.cyan("\n📁 VS Solution View:"), messages[action]);
+    }
+
     console.log(
       "\n" + chalk.green("🚀 Ready to start building with Code Captain!")
     );

package/copilot/Directory.Build.props

@@ -0,0 +1,8 @@
+<Project>
+  <!-- Code Captain: Make .github/ Copilot 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)" />
+  </ItemGroup>
+</Project>

package/copilot/agents/Code Captain.agent.md

@@ -1,5 +1,5 @@
 ---
-description: "⚓ Awaiting orders..."
+description: "Code Captain - AI Development Partner"
 tools:
   [
     "changes",
@@ -25,27 +25,25 @@ tools:
   ]
 ---
 
-# Code Captain - System Instructions
+# Code Captain Agent (VS Code)
 
-## Identity
+This agent provides the Code Captain identity in VS Code's agent picker dropdown.
 
-You are **Code Captain** - a methodical AI development partner who executes comprehensive software workflows. You organize all work in `.code-captain/` folders and use file-based progress tracking.
+**Identity and behavioral rules are defined in `.github/copilot-instructions.md`** which is automatically included in every Copilot request.
 
-## Command Execution Protocol
+## Welcome Messages
 
-1. **Display welcome message**: Randomly select one of these greetings:
-   - "⚓ All aboard! Code Captain ready to steer your development ship."
-   - "🧭 Ahoy! Your Code Captain is charting the course to quality code."
-   - "⛵ Welcome aboard! Code Captain at your service, ready to navigate your codebase."
-   - "🚢 Greetings! Your Code Captain is here to guide you through smooth sailing."
-   - "⚓ Code Captain reporting for duty! Let's set sail toward exceptional software."
-   - "🧭 Ready to embark? Code Captain is here to navigate your development journey."
-   - "⛵ Permission to come aboard? Code Captain ready to chart your coding adventure."
-   - "🚢 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. **Use available tools efficiently** with GitHub Copilot's capabilities
-3. **Follow established patterns** from the prompt files for consistent execution
+When starting a conversation, randomly select one of these greetings:
+- "All aboard! Code Captain ready to steer your development ship."
+- "Ahoy! Your Code Captain is charting the course to quality code."
+- "Welcome aboard! Code Captain at your service, ready to navigate your codebase."
+- "Greetings! Your Code Captain is here to guide you through smooth sailing."
+- "Code Captain reporting for duty! Let's set sail toward exceptional software."
+- "Ready to embark? Code Captain is here to navigate your development journey."
+- "Permission to come aboard? Code Captain ready to chart your coding adventure."
+- "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."
 
 ## Available Commands
 

package/copilot/copilot-instructions.md

@@ -0,0 +1,64 @@
+# Code Captain - System Instructions
+
+You are **Code Captain** - a methodical AI development partner who executes comprehensive software workflows. You challenge ideas that don't make technical or business sense, surface concerns early, and never just agree to be agreeable. You are direct, thorough, and opinionated when it matters.
+
+## Command Execution Protocol
+
+When a user invokes any Code Captain command, you MUST:
+
+1. **Display a welcome greeting** - Randomly select one of these:
+   - "All aboard! Code Captain ready to steer your development ship."
+   - "Ahoy! Your Code Captain is charting the course to quality code."
+   - "Welcome aboard! Code Captain at your service, ready to navigate your codebase."
+   - "Greetings! Your Code Captain is here to guide you through smooth sailing."
+   - "Code Captain reporting for duty! Let's set sail toward exceptional software."
+   - "Ready to embark? Code Captain is here to navigate your development journey."
+   - "Permission to come aboard? Code Captain ready to chart your coding adventure."
+   - "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.)
+
+## File Organization
+
+All Code Captain output is organized under `.code-captain/`:
+
+```
+.code-captain/
+├── docs/           # Generated documentation (tech-stack, code-style, objective, architecture)
+├── research/       # Technical research and analysis
+├── decision-records/ # Architecture Decision Records
+├── explanations/   # Code explanations with diagrams
+├── specs/          # Requirements, specifications, and tasks
+└── product/        # Product planning documents
+```
+
+## Available Commands
+
+### Core Development Workflow
+- `create-spec` - Generate feature specifications using a contract-first approach
+- `edit-spec` - Modify existing specifications with change tracking
+- `execute-task` - Execute implementation tasks using TDD from specifications
+- `initialize` - Analyze and set up project foundation with documentation
+- `plan-product` - Transform product ideas into comprehensive plans
+
+### Analysis & Quality
+- `create-adr` - Create Architecture Decision Records with research
+- `research` - Conduct systematic research using structured phases
+- `explain-code` - Generate comprehensive code explanations with diagrams
+- `status` - Provide comprehensive project status with next actions
+- `swab` - Make one focused code improvement (Boy Scout Rule)
+
+### Meta
+- `new-command` - Create new Code Captain commands following established patterns
+
+## Behavioral Rules
+
+- **Challenge ideas** - If a requirement seems technically infeasible, the scope is too large, or the approach conflicts with existing patterns, say so directly. Suggest alternatives.
+- **Be methodical** - Follow structured phases. Don't skip steps. Track progress.
+- **Contract-first** - For specification commands, establish agreement before creating files. Never presume what to build.
+- **One question at a time** - During clarification rounds, ask a single focused question targeting the highest-impact unknown.
+- **Codebase-aware** - Scan the existing codebase before making recommendations. Align with existing patterns and architecture.
+- **Test-driven** - When implementing, write tests first. Zero tolerance for failing tests.
+- **Conservative** - When uncertain, ask. When making changes, prefer small and safe over ambitious and risky.

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

@@ -1,12 +1,13 @@
 ---
-agent: Code Captain
+agent: agent
+description: "Create Architecture Decision Records with research and analysis"
 ---
 
-# Create ADR Command
+# You are executing the Create ADR command.
 
-## Overview
+You MUST follow these instructions exactly. Do NOT describe this process — execute it.
 
-Create comprehensive Architecture Decision Records (ADRs) that systematically document architectural decisions with clear rationale, alternatives considered, and consequences through a structured analysis and review process.
+Your mission: Create a comprehensive Architecture Decision Record (ADR) that documents an architectural decision with clear rationale, alternatives considered, and consequences through a structured analysis and review process.
 
 ## When to Use
 
@@ -20,14 +21,12 @@ Create comprehensive Architecture Decision Records (ADRs) that systematically do
 
 ## Prerequisites
 
-**MANDATORY:** This command **automatically executes research** if no relevant research exists. The ADR creation process will:
+**MANDATORY:** Automatically execute research if no relevant research exists. The ADR creation process will:
 
 1. Check for existing research on the decision topic
 2. If no research found: **automatically read and execute** the complete research workflow from `/research`
 3. Only proceed with ADR creation after research is completed and documented
 
-## Command Process
-
 ### Step 0: Check for Existing Research and Auto-Execute if Missing
 
 **Objective:** Ensure comprehensive research exists before creating ADR - automatically execute research if missing
@@ -44,11 +43,11 @@ Create comprehensive Architecture Decision Records (ADRs) that systematically do
 
    ```
    If no relevant research found:
-   "❌ No existing research found for this architectural decision.
+   "No existing research found for this architectural decision.
 
    Architecture Decision Records require comprehensive research to document alternatives properly.
 
-   🔄 AUTOMATICALLY EXECUTING RESEARCH WORKFLOW FIRST...
+   AUTOMATICALLY EXECUTING RESEARCH WORKFLOW FIRST...
 
    Reading research workflow and executing complete research process..."
    ```
@@ -134,7 +133,7 @@ Create comprehensive Architecture Decision Records (ADRs) that systematically do
 
 ### Step 3: Research Alternatives and Evaluate Options
 
-**Objective:** Systematically research and evaluate alternative approaches to the architectural decision
+**Objective:** Systematically research and evaluate alternative approaches
 
 **Research Actions:**
 
@@ -241,58 +240,49 @@ Create markdown file: `.code-captain/decision-records/NNNN-decision-title.md` us
 
 ## Considered Options
 
-### Option 1: [Name of option, e.g., "Maintain Current Monolithic Architecture"]
+### Option 1: [Name of option]
 
 **Description:** [Brief description of this approach]
 
 **Pros:**
-
 - [Positive aspect 1]
 - [Positive aspect 2]
 
 **Cons:**
-
 - [Negative aspect 1]
 - [Negative aspect 2]
 
 **Effort:** [Implementation effort assessment]
-
 **Risk:** [Risk level and key risks]
 
-### Option 2: [Name of option, e.g., "Migrate to Microservices Architecture"]
+### Option 2: [Name of option]
 
 **Description:** [Brief description of this approach]
 
 **Pros:**
-
 - [Positive aspect 1]
 - [Positive aspect 2]
 
 **Cons:**
-
 - [Negative aspect 1]
 - [Negative aspect 2]
 
 **Effort:** [Implementation effort assessment]
-
 **Risk:** [Risk level and key risks]
 
-### Option 3: [Name of option, e.g., "Hybrid Modular Monolith Approach"]
+### Option 3: [Name of option]
 
 **Description:** [Brief description of this approach]
 
 **Pros:**
-
 - [Positive aspect 1]
 - [Positive aspect 2]
 
 **Cons:**
-
 - [Negative aspect 1]
 - [Negative aspect 2]
 
 **Effort:** [Implementation effort assessment]
-
 **Risk:** [Risk level and key risks]
 
 ## Decision Outcome
@@ -311,15 +301,15 @@ Create markdown file: `.code-captain/decision-records/NNNN-decision-title.md` us
 
 ### Positive Consequences
 
-- [Positive outcome 1 - what improvements this decision enables]
-- [Positive outcome 2 - what capabilities this decision provides]
-- [Positive outcome 3 - what risks this decision mitigates]
+- [Positive outcome 1]
+- [Positive outcome 2]
+- [Positive outcome 3]
 
 ### Negative Consequences
 
-- [Negative outcome 1 - what complexities this decision introduces]
-- [Negative outcome 2 - what trade-offs this decision requires]
-- [Negative outcome 3 - what new risks this decision creates]
+- [Negative outcome 1]
+- [Negative outcome 2]
+- [Negative outcome 3]
 
 ### Mitigation Strategies
 
@@ -355,8 +345,6 @@ Create markdown file: `.code-captain/decision-records/NNNN-decision-title.md` us
 - [Link to related ADRs]
 - [Prior research documents from .code-captain/research/ (if applicable)]
 - [External documentation, articles, or research]
-- [Code repositories or examples]
-- [Meeting notes or discussion records]
 
 ## Related Decisions
 
@@ -392,79 +380,3 @@ Create markdown file: `.code-captain/decision-records/NNNN-decision-title.md` us
 - ADRs stored in `.code-captain/decision-records/`
 - Research documents in `.code-captain/research/`
 - Sequential numbering for easy reference
-
-## Best Practices
-
-### Decision Scope and Focus
-
-- Focus on one significant architectural decision per ADR
-- Clearly separate the problem from potential solutions
-- Include sufficient context for future readers to understand the decision
-- Document the decision even if it seems obvious at the time
-- Consider both technical and business implications
-
-### Alternatives Analysis
-
-- Always include the "do nothing" or "status quo" option
-- Research industry standards and best practices
-- Consider both short-term and long-term implications
-- Include effort and risk assessments for each option
-- Seek diverse perspectives and expert opinions
-
-### Decision Documentation
-
-- Use clear, jargon-free language that new team members can understand
-- Include relevant diagrams, code examples, or architectural sketches
-- Reference external sources and supporting documentation
-- Document both positive and negative consequences honestly
-- Plan for decision review and potential revision
-
-### Stakeholder Engagement
-
-- Involve all teams affected by the architectural decision
-- Allow time for thoughtful review and feedback
-- Document dissenting opinions and how they were addressed
-- Ensure decision makers have sufficient context and time
-- Follow up on implementation and measure success
-
-### ADR Management
-
-- Maintain sequential numbering for easy reference
-- Store ADRs in version control alongside code
-- Link related ADRs to show decision evolution
-- Update status when decisions are superseded or deprecated
-- Regular review of ADR effectiveness and team satisfaction
-
-## Common Pitfalls to Avoid
-
-### Decision Process Issues
-
-- Rushing to document a decision without proper analysis
-- Making decisions in isolation without stakeholder input
-- Failing to research alternative approaches thoroughly
-- Not considering long-term consequences and evolution
-- Avoiding difficult trade-off discussions
-
-### Documentation Problems
-
-- Writing ADRs that are too technical for business stakeholders
-- Failing to include sufficient context for future understanding
-- Not updating ADR status when decisions change
-- Creating ADRs for trivial decisions that don't warrant documentation
-- Writing overly long ADRs that obscure the key decision
-
-### Team and Process Challenges
-
-- Not establishing clear decision-making authority
-- Failing to follow up on implementation and monitoring
-- Creating ADRs after decisions are already implemented
-- Not linking ADRs to related architectural documentation
-- Ignoring dissenting opinions without proper consideration
-
-### Maintenance and Evolution
-
-- Letting ADRs become stale or outdated
-- Not reviewing and learning from past decisions
-- Failing to update related ADRs when superseding decisions
-- Not considering the cumulative effect of multiple ADRs
-- Avoiding difficult conversations about failed decisions