@devobsessed/code-captain 0.1.0 → 0.2.1

package/copilot/README.md

@@ -1,8 +1,8 @@
 # Code Captain for GitHub Copilot + VS Code
 
-> **Classic VS Code with AI-powered chat modes and prompts**
+> **Classic VS Code with AI-powered agents and prompts**
 
-Transform GitHub Copilot Chat into a structured development workflow system with custom chat modes, prompts, and organized documentation.
+Transform GitHub Copilot Chat into a structured development workflow system with custom agents, prompts, and organized documentation.
 
 ## 🚀 Installation
 
@@ -13,7 +13,7 @@ npx @devobsessed/code-captain
 ```
 
 The installer will detect VS Code with Copilot and install to:
-- `.github/chatmodes/` - Code Captain chat mode
+- `.github/agents/` - Code Captain agent
 - `.github/prompts/` - Workflow prompt templates
 - `.code-captain/` - Complete workflow system
 
@@ -21,16 +21,16 @@ The installer will detect VS Code with Copilot and install to:
 
 ```bash
 # Clone or download the copilot/ directory contents to .github/
-cp -r copilot/chatmodes/ .github/chatmodes/
+cp -r copilot/agents/ .github/agents/
 cp -r copilot/prompts/ .github/prompts/
 cp -r .code-captain/ .
 ```
 
 ## 🎯 Command Syntax
 
-Code Captain integrates with Copilot Chat through a custom chat mode. After installation:
+Code Captain integrates with Copilot Chat through a custom agent. After installation:
 
-1. **Select Code Captain chat mode** from the chat mode dropdown
+1. **Select Code Captain agent** from the agent picker
 2. **Use slash commands** directly:
 
 ```bash
@@ -40,12 +40,12 @@ Code Captain integrates with Copilot Chat through a custom chat mode. After inst
 /status
 ```
 
-## 📁 Chat Modes & Prompts
+## 📁 Agents & Prompts
 
-### Chat Mode
-Located in `.github/chatmodes/`:
+### Agent
+Located in `.github/agents/`:
 
-- **Code Captain.chatmode.md** - Automatically available in chat mode selector
+- **Code Captain.agent.md** - Automatically available in agent picker
 
 ### Available Prompts
 Located in `.github/prompts/`:
@@ -66,7 +66,7 @@ Located in `.github/prompts/`:
 
 ### 📋 Analysis & Research
 - **Research Topics**: AI/ML frameworks, database patterns, security approaches
-- **Market Analysis**: Competitive landscapes, feature comparisons  
+- **Market Analysis**: Competitive landscapes, feature comparisons
 - **Technical Evaluation**: Library assessments, architecture reviews
 
 ### ⚙️ Implementation
@@ -78,7 +78,7 @@ Located in `.github/prompts/`:
 
 ### Phase 1: Enhanced Core Features ✅
 1. **Advanced Analysis** - Multi-language support, framework detection
-2. **Rich Specifications** - Visual diagrams, interaction flows, API schemas  
+2. **Rich Specifications** - Visual diagrams, interaction flows, API schemas
 3. **Smart Implementation** - Context-aware code generation, test automation
 
 ### Phase 2: Quality & Collaboration 🚧
@@ -93,10 +93,10 @@ Located in `.github/prompts/`:
 
 ## 🔄 Workflow Examples
 
-### Using the Chat Mode
+### Using the Agent
 
 1. **Open Copilot Chat** in VS Code
-2. **Select "Code Captain"** from the chat mode dropdown
+2. **Select "Code Captain"** from the agent picker
 3. **Type:** `/initialize`
 4. **Follow the prompts** for project analysis
 5. **Review generated files** in `.code-captain/docs/`
@@ -111,7 +111,7 @@ Located in `.github/prompts/`:
 ### Complete Feature Development
 
 ```bash
-# Select "Code Captain" chat mode, then:
+# Select "Code Captain" agent, then:
 
 # 1. Project setup
 /initialize
@@ -138,8 +138,8 @@ Copilot integration creates this structure:
 
 ```
 .github/
-├── chatmodes/
-│   └── Code Captain.chatmode.md
+├── agents/
+│   └── Code Captain.agent.md
 └── prompts/
     ├── create-spec.prompt.md
     ├── create-adr.prompt.md
@@ -163,8 +163,8 @@ Copilot integration creates this structure:
 
 ## 🎯 Copilot-Specific Features
 
-### Custom Chat Modes
-- **Structured workflows** through chat mode activation
+### Custom Agents
+- **Structured workflows** through agent activation
 - **Context-aware responses** based on project state
 - **Guided interactions** with step-by-step processes
 
@@ -175,7 +175,7 @@ Copilot integration creates this structure:
 
 ### Repository Integration
 - **Repository-based configuration** through `.github/` structure
-- **Team collaboration** through shared chat modes and prompts
+- **Team collaboration** through shared agents and prompts
 - **Version-controlled workflows** alongside your codebase
 
 
@@ -190,23 +190,23 @@ Copilot integration creates this structure:
 
 ## 🛠️ Troubleshooting
 
-### Chat Mode Not Available
-**Problem**: Code Captain doesn't appear in chat mode selector  
-**Solution**: Ensure `.github/chatmodes/Code Captain.chatmode.md` exists and restart VS Code
+### Agent Not Available
+**Problem**: Code Captain doesn't appear in agent picker
+**Solution**: Ensure `.github/agents/Code Captain.agent.md` exists and restart VS Code
 
 ### Prompts Don't Work as Expected
-**Problem**: Prompts generate inconsistent results  
+**Problem**: Prompts generate inconsistent results
 **Solution**: Copy the exact prompt text and include all context sections
 
 ### File Generation Issues
-**Problem**: Files aren't created in expected locations  
+**Problem**: Files aren't created in expected locations
 **Solution**: Check `.code-captain/` folder exists and has write permissions
 
 ## 🤝 Contributing
 
 Copilot-specific contributions:
 
-1. **Chat Mode Enhancement** - Improve workflow integration
+1. **Agent Enhancement** - Improve workflow integration
 2. **Prompt Templates** - Add new workflow templates
 3. **Documentation** - Add Copilot-specific examples
 4. **Repository Integration** - Enhance repository templates
@@ -217,4 +217,4 @@ Copilot-specific contributions:
 
 1. **Install:** `npx @devobsessed/code-captain`
 2. **Open:** Copilot Chat in VS Code
-3. **Start:** Select "Code Captain" mode and type `/initialize` 
+3. **Start:** Select "Code Captain" agent and type `/initialize`

package/copilot/{chatmodes/Code Captain.chatmode.md → 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 @@
 ---
-mode: agent
+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