diff --git a/README.md b/README.md index e6a57dc..0e3d048 100644 --- a/README.md +++ b/README.md @@ -19,6 +19,8 @@ The philosophy behind Conductor is simple: control your code. By treating contex ## Installation +### Gemini CLI Extension + Install the Conductor extension by running the following command from your terminal: ```bash @@ -27,6 +29,28 @@ gemini extensions install https://github.com/gemini-cli-extensions/conductor --a The `--auto-update` is optional: if specified, it will update to new versions as they are released. +### AI Agent Skill (Claude CLI / OpenCode / Codex) + +Conductor is also available as a portable **skill** that works with Claude CLI, OpenCode, and other AI coding agents that support the skills standard. + +```bash +# Clone the repository +git clone https://github.com/gemini-cli-extensions/conductor.git +cd conductor + +# Run the install script +./skill/scripts/install.sh +``` + +The installer will ask where to install: +1. **OpenCode global** (`~/.opencode/skill/conductor/`) +2. **Claude CLI global** (`~/.claude/skills/conductor/`) +3. **Both** + +The skill is installed with symlinks to this repository, so running `git pull` will automatically update the skill. + +After installation, restart your AI CLI. The agent will automatically detect and use Conductor when you ask to create a new feature, write a spec, plan a feature, or set up a project. + ## Usage Conductor is designed to manage the entire lifecycle of your development tasks. diff --git a/skill/SKILL.md b/skill/SKILL.md new file mode 100644 index 0000000..586a97a --- /dev/null +++ b/skill/SKILL.md @@ -0,0 +1,94 @@ +--- +name: conductor +description: Use when the user wants to setup a new project, create a new feature, write a spec, plan a feature, fix a bug with a plan, start a new track, check project status, implement next task, or revert changes. Also use when user mentions "conductor", "track", or "spec-driven development". If conductor is not yet configured in the project, start with setup. +--- + +# Conductor + +Conductor is a Context-Driven Development (CDD) framework that transforms AI agents into proactive project managers. The philosophy is "Measure twice, code once" - every feature follows a strict protocol: **Context -> Spec & Plan -> Implement**. + +## Core Concepts + +- **Track**: A unit of work (feature or bug fix) with its own spec and plan +- **Spec**: Detailed requirements document (`spec.md`) +- **Plan**: Phased task list with checkboxes (`plan.md`) +- **Workflow**: Rules for task lifecycle, TDD, commits, and quality gates + +## Directory Structure + +When initialized, Conductor creates this structure in the project: + +``` +conductor/ +├── product.md # Product vision and goals +├── product-guidelines.md # UX/brand guidelines +├── tech-stack.md # Technology choices +├── workflow.md # Development workflow rules +├── tracks.md # Master list of all tracks +├── code_styleguides/ # Language-specific style guides +├── tracks/ # Active tracks +│ └── / +│ ├── metadata.json +│ ├── spec.md +│ └── plan.md +└── archive/ # Completed tracks +``` + +## Available Commands + +| Command | Purpose | +|---------|---------| +| **Setup** | Initialize Conductor in a project (new or existing) | +| **New Track** | Create a new feature/bug track with spec and plan | +| **Implement** | Execute tasks from a track's plan following TDD workflow | +| **Status** | Show progress overview of all tracks | +| **Revert** | Git-aware rollback of tracks, phases, or tasks | + +## Protocol References + +The detailed protocols are in TOML format. Read the `prompt` field from each file: + +| Action | Protocol File | +|--------|---------------| +| Setup project | `commands/conductor/setup.toml` | +| Create new track | `commands/conductor/newTrack.toml` | +| Implement tasks | `commands/conductor/implement.toml` | +| Check status | `commands/conductor/status.toml` | +| Revert changes | `commands/conductor/revert.toml` | + +**How to read**: Each `.toml` file has a `prompt` field containing the full protocol instructions. + +## Task Status Markers + +- `[ ]` - Pending +- `[~]` - In Progress +- `[x]` - Completed + +## Key Workflow Principles + +1. **The Plan is Source of Truth**: All work tracked in `plan.md` +2. **Test-Driven Development**: Write tests before implementing +3. **High Code Coverage**: Target >80% coverage +4. **Commit After Each Task**: With git notes for traceability +5. **Phase Checkpoints**: Manual verification at phase completion + +## When to Use Each Protocol + +- **"set up conductor" or "initialize project"** -> Read `commands/conductor/setup.toml` +- **"new feature", "new track", "plan a feature"** -> Read `commands/conductor/newTrack.toml` +- **"implement", "start working", "next task"** -> Read `commands/conductor/implement.toml` +- **"status", "progress", "where are we"** -> Read `commands/conductor/status.toml` +- **"revert", "undo", "rollback"** -> Read `commands/conductor/revert.toml` + +## Assets + +- **Code Styleguides**: `templates/code_styleguides/` (general, go, python, javascript, typescript, html-css) +- **Workflow Template**: `templates/workflow.md` + +## Critical Rules + +1. **Validate every tool call** - If any fails, halt and report to user +2. **Sequential questions** - Ask one question at a time, wait for response +3. **User confirmation required** - Before writing files or making changes +4. **Check setup first** - Verify `conductor/` exists before any operation +5. **Agnostic language** - Do not suggest slash commands like `/conductor:xxx`. Instead, tell the user to ask you directly (e.g., "to start implementing, just ask me" instead of "run /conductor:implement") diff --git a/skill/scripts/install.sh b/skill/scripts/install.sh new file mode 100755 index 0000000..caafafe --- /dev/null +++ b/skill/scripts/install.sh @@ -0,0 +1,89 @@ +#!/bin/bash +# Install Conductor skill for Claude CLI / OpenCode +# Usage: ./install.sh +# +# This script creates a skill directory with symlinks to the Conductor repository, +# so updates to the repo are automatically reflected in the skill. + +set -e + +SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)" +SKILL_DIR="$(dirname "$SCRIPT_DIR")" +CONDUCTOR_ROOT="$(dirname "$SKILL_DIR")" + +echo "Conductor Skill Installer" +echo "=========================" +echo "" + +# Check if we're running from within a conductor repo +if [ ! -f "$CONDUCTOR_ROOT/commands/conductor/setup.toml" ]; then + echo "Error: This script must be run from within the Conductor repository." + echo "Expected to find: $CONDUCTOR_ROOT/commands/conductor/setup.toml" + echo "" + echo "Please clone the repository first:" + echo " git clone https://github.com/gemini-cli-extensions/conductor.git" + echo " cd conductor" + echo " ./skill/scripts/install.sh" + exit 1 +fi + +echo "Conductor repository found at: $CONDUCTOR_ROOT" +echo "" +echo "Where do you want to install the skill?" +echo "" +echo " 1) OpenCode global (~/.opencode/skill/conductor/)" +echo " 2) Claude CLI global (~/.claude/skills/conductor/)" +echo " 3) Both" +echo "" +read -p "Choose [1/2/3]: " choice + +case "$choice" in + 1) + TARGETS=("$HOME/.opencode/skill/conductor") + ;; + 2) + TARGETS=("$HOME/.claude/skills/conductor") + ;; + 3) + TARGETS=("$HOME/.opencode/skill/conductor" "$HOME/.claude/skills/conductor") + ;; + *) + echo "Invalid choice. Exiting." + exit 1 + ;; +esac + +for TARGET_DIR in "${TARGETS[@]}"; do + echo "" + echo "Installing to: $TARGET_DIR" + + # Remove existing installation + rm -rf "$TARGET_DIR" + + # Create skill directory + mkdir -p "$TARGET_DIR" + + # Copy SKILL.md (the only actual file) + cp "$SKILL_DIR/SKILL.md" "$TARGET_DIR/" + + # Create symlinks to conductor repo directories + ln -s "$CONDUCTOR_ROOT/commands" "$TARGET_DIR/commands" + ln -s "$CONDUCTOR_ROOT/templates" "$TARGET_DIR/templates" + + echo " Created: $TARGET_DIR/SKILL.md" + echo " Symlink: $TARGET_DIR/commands -> $CONDUCTOR_ROOT/commands" + echo " Symlink: $TARGET_DIR/templates -> $CONDUCTOR_ROOT/templates" +done + +echo "" +echo "Conductor skill installed successfully!" +echo "" +echo "Structure:" +for TARGET_DIR in "${TARGETS[@]}"; do + ls -la "$TARGET_DIR" 2>/dev/null || true +done +echo "" +echo "The skill references the Conductor repo at: $CONDUCTOR_ROOT" +echo "Updates to the repo (git pull) will be reflected automatically." +echo "" +echo "Restart your AI CLI to load the skill."