[Spec 0039] TICK-001 + TICK-002: Consult consolidation & Embedded skeleton

AGENTS.md

@@ -415,37 +415,37 @@ The `consult` CLI provides a unified interface for single-agent consultation via
 
 ```
 # ✅ CORRECT - Two separate Bash tool calls in one message
-[Bash tool call 1]: ./codev/bin/consult --model gemini spec 39
-[Bash tool call 2]: ./codev/bin/consult --model codex spec 39
+[Bash tool call 1]: consult --model gemini spec 39
+[Bash tool call 2]: consult --model codex spec 39
 
 # ❌ WRONG - Sequential tool calls in separate messages
-[Message 1, Bash]: ./codev/bin/consult --model gemini spec 39
-[Message 2, Bash]: ./codev/bin/consult --model codex spec 39
+[Message 1, Bash]: consult --model gemini spec 39
+[Message 2, Bash]: consult --model codex spec 39
 ```
 
 ### Prerequisites
 
-- **Python 3**: With typer installed (`pip install typer`)
+- **@cluesmith/codev**: `npm install -g @cluesmith/codev` (provides `consult` binary)
 - **gemini-cli**: For Gemini consultations (see https://github.com/google-gemini/gemini-cli)
 - **codex**: For Codex consultations (`npm install -g @openai/codex`)
 - **claude**: For Claude consultations (`npm install -g @anthropic-ai/claude-code`)
 
 ### Usage
 
 ```bash
-# Subcommand-based interface (preferred)
-./codev/bin/consult --model gemini pr 33        # Review a PR
-./codev/bin/consult --model codex spec 39       # Review a spec
-./codev/bin/consult --model claude plan 39      # Review a plan
-./codev/bin/consult --model gemini general "Review this design"  # General query
+# Subcommand-based interface
+consult --model gemini pr 33        # Review a PR
+consult --model codex spec 39       # Review a spec
+consult --model claude plan 39      # Review a plan
+consult --model gemini general "Review this design"  # General query
 
 # Model aliases work too
-./codev/bin/consult --model pro spec 39    # alias for gemini
-./codev/bin/consult --model gpt pr 33      # alias for codex
-./codev/bin/consult --model opus plan 39   # alias for claude
+consult --model pro spec 39    # alias for gemini
+consult --model gpt pr 33      # alias for codex
+consult --model opus plan 39   # alias for claude
 
 # Dry run (print command without executing)
-./codev/bin/consult --model gemini spec 39 --dry-run
+consult --model gemini spec 39 --dry-run
 ```
 
 ### Parallel Consultation (3-Way Reviews)
@@ -454,16 +454,16 @@ For 3-way reviews, run consultations in parallel using separate Bash tool calls:
 
 ```bash
 # All three in parallel (separate Bash tool calls in same message)
-./codev/bin/consult --model gemini spec 39
-./codev/bin/consult --model codex spec 39
-./codev/bin/consult --model claude spec 39
+consult --model gemini spec 39
+consult --model codex spec 39
+consult --model claude spec 39
 ```
 
 Or use background processes in a single shell:
 ```bash
-./codev/bin/consult --model gemini spec 39 &
-./codev/bin/consult --model codex spec 39 &
-./codev/bin/consult --model claude spec 39 &
+consult --model gemini spec 39 &
+consult --model codex spec 39 &
+consult --model claude spec 39 &
 wait
 ```
 
@@ -540,7 +540,8 @@ The consultant role (`codev/roles/consultant.md`) defines a collaborative partne
 
 ### Key Files
 
-- `codev/bin/consult` - Python CLI script
+- `packages/codev/src/commands/consult/index.ts` - TypeScript implementation
+- `codev/bin/consult` - Backwards-compatible shim (delegates to TypeScript)
 - `codev/roles/consultant.md` - Role definition
 - `.consult/history.log` - Query history with timing (gitignored)
 

CLAUDE.md

@@ -415,37 +415,37 @@ The `consult` CLI provides a unified interface for single-agent consultation via
 
 ```
 # ✅ CORRECT - Two separate Bash tool calls in one message
-[Bash tool call 1]: ./codev/bin/consult --model gemini spec 39
-[Bash tool call 2]: ./codev/bin/consult --model codex spec 39
+[Bash tool call 1]: consult --model gemini spec 39
+[Bash tool call 2]: consult --model codex spec 39
 
 # ❌ WRONG - Sequential tool calls in separate messages
-[Message 1, Bash]: ./codev/bin/consult --model gemini spec 39
-[Message 2, Bash]: ./codev/bin/consult --model codex spec 39
+[Message 1, Bash]: consult --model gemini spec 39
+[Message 2, Bash]: consult --model codex spec 39
 ```
 
 ### Prerequisites
 
-- **Python 3**: With typer installed (`pip install typer`)
+- **@cluesmith/codev**: `npm install -g @cluesmith/codev` (provides `consult` binary)
 - **gemini-cli**: For Gemini consultations (see https://github.com/google-gemini/gemini-cli)
 - **codex**: For Codex consultations (`npm install -g @openai/codex`)
 - **claude**: For Claude consultations (`npm install -g @anthropic-ai/claude-code`)
 
 ### Usage
 
 ```bash
-# Subcommand-based interface (preferred)
-./codev/bin/consult --model gemini pr 33        # Review a PR
-./codev/bin/consult --model codex spec 39       # Review a spec
-./codev/bin/consult --model claude plan 39      # Review a plan
-./codev/bin/consult --model gemini general "Review this design"  # General query
+# Subcommand-based interface
+consult --model gemini pr 33        # Review a PR
+consult --model codex spec 39       # Review a spec
+consult --model claude plan 39      # Review a plan
+consult --model gemini general "Review this design"  # General query
 
 # Model aliases work too
-./codev/bin/consult --model pro spec 39    # alias for gemini
-./codev/bin/consult --model gpt pr 33      # alias for codex
-./codev/bin/consult --model opus plan 39   # alias for claude
+consult --model pro spec 39    # alias for gemini
+consult --model gpt pr 33      # alias for codex
+consult --model opus plan 39   # alias for claude
 
 # Dry run (print command without executing)
-./codev/bin/consult --model gemini spec 39 --dry-run
+consult --model gemini spec 39 --dry-run
 ```
 
 ### Parallel Consultation (3-Way Reviews)
@@ -454,16 +454,16 @@ For 3-way reviews, run consultations in parallel using separate Bash tool calls:
 
 ```bash
 # All three in parallel (separate Bash tool calls in same message)
-./codev/bin/consult --model gemini spec 39
-./codev/bin/consult --model codex spec 39
-./codev/bin/consult --model claude spec 39
+consult --model gemini spec 39
+consult --model codex spec 39
+consult --model claude spec 39
 ```
 
 Or use background processes in a single shell:
 ```bash
-./codev/bin/consult --model gemini spec 39 &
-./codev/bin/consult --model codex spec 39 &
-./codev/bin/consult --model claude spec 39 &
+consult --model gemini spec 39 &
+consult --model codex spec 39 &
+consult --model claude spec 39 &
 wait
 ```
 
@@ -540,7 +540,8 @@ The consultant role (`codev/roles/consultant.md`) defines a collaborative partne
 
 ### Key Files
 
-- `codev/bin/consult` - Python CLI script
+- `packages/codev/src/commands/consult/index.ts` - TypeScript implementation
+- `codev/bin/consult` - Backwards-compatible shim (delegates to TypeScript)
 - `codev/roles/consultant.md` - Role definition
 - `.consult/history.log` - Query history with timing (gitignored)
 

INSTALL.md

@@ -35,6 +35,37 @@ codev doctor
 
 ---
 
+## How It Works: Embedded Skeleton with Local Overrides
+
+When you install `@cluesmith/codev`, the package includes all framework files (protocols, roles, agents) as an **embedded skeleton**. This means:
+
+1. **Minimal project structure**: `codev init` and `codev adopt` only create:
+   - `codev/specs/` - Your feature specifications
+   - `codev/plans/` - Your implementation plans
+   - `codev/reviews/` - Your reviews and lessons learned
+   - `codev/projectlist.md` - Project tracking
+   - `CLAUDE.md` and `AGENTS.md` - AI agent instructions
+
+2. **Framework files provided at runtime**: Protocols, roles, and templates are read from the installed npm package, not copied to your project. This keeps your project clean and makes updates seamless.
+
+3. **Local overrides supported**: If you want to customize any framework file, simply create it in your local `codev/` directory. Local files always take precedence:
+   - To customize the consultant role: create `codev/roles/consultant.md`
+   - To modify SPIDER protocol: create `codev/protocols/spider/protocol.md`
+   - To add custom templates: create files in `codev/templates/`
+
+### Example: Customizing a Role
+
+```bash
+# Copy the default consultant role to your project for customization
+mkdir -p codev/roles
+cat $(npm root -g)/@cluesmith/codev/skeleton/roles/consultant.md > codev/roles/consultant.md
+
+# Edit it to suit your needs
+# The local version will now be used instead of the embedded one
+```
+
+---
+
 ## Alternative: Manual Installation for AI Agents
 
 This section provides instructions for AI agents to manually install the Codev methodology framework. Most users should use `npm install -g @cluesmith/codev` instead.

README.md

@@ -124,23 +124,41 @@ Our flagship protocol for structured development:
 
 ## Project Structure
 
+After running `codev init` or `codev adopt`, your project has a **minimal structure**:
+
 ```
 your-project/
 ├── codev/
-│   ├── protocols/
-│   │   └── spider/          # The SP(IDE)R protocol
-│   │       ├── protocol.md  # Detailed protocol documentation
-│   │       ├── manifest.yaml
-│   │       └── templates/   # Document templates
 │   ├── specs/              # Feature specifications
 │   ├── plans/              # Implementation plans
 │   ├── reviews/            # Review and lessons learned
-│   └── resources/          # Reference materials (llms.txt, etc.)
+│   └── projectlist.md      # Project tracking
 ├── AGENTS.md               # AI agent instructions (AGENTS.md standard)
 ├── CLAUDE.md               # AI agent instructions (Claude Code)
 └── [your code]
 ```
 
+**Framework files are provided at runtime** by the `@cluesmith/codev` package. This includes:
+- Protocols (SPIDER, TICK, EXPERIMENT, MAINTAIN)
+- Roles (architect, builder, consultant)
+- Templates and agents
+
+### Customizing Framework Files
+
+If you need to customize any framework file, create it in your local `codev/` directory. **Local files always take precedence** over the embedded skeleton:
+
+```bash
+# Example: Customize the SPIDER protocol
+mkdir -p codev/protocols/spider
+cp $(npm root -g)/@cluesmith/codev/skeleton/protocols/spider/protocol.md codev/protocols/spider/
+
+# Example: Customize a role
+mkdir -p codev/roles
+cp $(npm root -g)/@cluesmith/codev/skeleton/roles/consultant.md codev/roles/
+```
+
+This approach keeps your project clean while allowing full customization when needed.
+
 ## Key Features
 
 ### 📄 Documents Are First-Class Citizens

codev-skeleton/DEPENDENCIES.md

@@ -130,26 +130,6 @@ gh auth login
 gh auth status  # Should show "Logged in to github.com"
 ```
 
-### Python 3
-
-| Requirement | Value |
-|-------------|-------|
-| Minimum Version | 3.10 |
-| Purpose | Consult tool, utility scripts |
-
-**Installation:**
-
-```bash
-# macOS
-brew install python
-
-# Ubuntu/Debian
-sudo apt install python3 python3-pip
-
-# Verify
-python3 --version  # Should show 3.10.x or higher
-```
-
 ---
 
 ## AI CLI Dependencies (At Least One Required)
@@ -206,30 +186,6 @@ codex --version
 
 ---
 
-## Python Packages (Optional)
-
-These are optional but enable additional features.
-
-### typer
-
-| Requirement | Value |
-|-------------|-------|
-| Purpose | CLI framework for the consult tool |
-
-**Installation:**
-
-```bash
-pip install typer
-
-# Or with uv
-uv pip install typer
-
-# Verify
-python3 -c "import typer; print('typer installed')"
-```
-
----
-
 ## Version Requirements Summary
 
 | Dependency | Minimum Version | Required? |
@@ -239,11 +195,9 @@ python3 -c "import typer; print('typer installed')"
 | ttyd | 1.7.0 | Yes |
 | git | 2.5.0 | Yes |
 | gh | latest | Yes |
-| Python 3 | 3.10 | Yes |
 | Claude Code | latest | At least one AI CLI |
 | Gemini CLI | latest | At least one AI CLI |
 | Codex CLI | latest | At least one AI CLI |
-| typer | latest | No (for consult tool) |
 
 ---
 
@@ -255,7 +209,7 @@ All dependencies are available via Homebrew:
 
 ```bash
 # Install all core dependencies at once
-brew install node tmux ttyd gh python
+brew install node tmux ttyd gh
 
 # Git is included with Xcode command line tools
 xcode-select --install
@@ -267,7 +221,7 @@ Most dependencies are available via apt, except ttyd which must be built from so
 
 ```bash
 # Core dependencies
-sudo apt install nodejs npm tmux git python3 python3-pip
+sudo apt install nodejs npm tmux git
 
 # gh requires adding GitHub's apt repository (see above)