From cac4bf39a637f6fa4cffa0f172221935cf8685bd Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 27 Jan 2026 01:37:26 +0000 Subject: [PATCH 1/3] feat: Add clone_remote_job skill and install_remote_job.sh script Add a new standalone skill to deepwork_jobs that allows users to install jobs from remote GitHub repositories (like the DeepWork job library). Changes: - Add install_remote_job.sh script that fetches job files from GitHub URLs - Add clone_remote_job.md step instructions for guiding customization - Update job.yml to version 1.1.0 with the new skill - Regenerate skills for all platforms - Update architecture.md and CHANGELOG.md --- .claude/settings.json | 3 +- .../deepwork_jobs.clone_remote_job/SKILL.md | 287 +++++++++++++++++ .claude/skills/deepwork_jobs.define/SKILL.md | 5 +- .../skills/deepwork_jobs.implement/SKILL.md | 5 +- .claude/skills/deepwork_jobs.learn/SKILL.md | 5 +- .../deepwork_jobs.review_job_spec/SKILL.md | 5 +- .claude/skills/deepwork_jobs/SKILL.md | 8 +- .../jobs/deepwork_jobs/install_remote_job.sh | 294 ++++++++++++++++++ .deepwork/jobs/deepwork_jobs/job.yml | 29 +- .../deepwork_jobs/steps/clone_remote_job.md | 197 ++++++++++++ .../deepwork_jobs/clone_remote_job.toml | 277 +++++++++++++++++ .gemini/skills/deepwork_jobs/define.toml | 9 +- .gemini/skills/deepwork_jobs/implement.toml | 9 +- .gemini/skills/deepwork_jobs/index.toml | 8 +- .gemini/skills/deepwork_jobs/learn.toml | 5 +- .../skills/deepwork_jobs/review_job_spec.toml | 9 +- CHANGELOG.md | 6 +- doc/architecture.md | 1 + .../deepwork_jobs/install_remote_job.sh | 294 ++++++++++++++++++ .../standard_jobs/deepwork_jobs/job.yml | 29 +- .../deepwork_jobs/steps/clone_remote_job.md | 197 ++++++++++++ 21 files changed, 1660 insertions(+), 22 deletions(-) create mode 100644 .claude/skills/deepwork_jobs.clone_remote_job/SKILL.md create mode 100755 .deepwork/jobs/deepwork_jobs/install_remote_job.sh create mode 100644 .deepwork/jobs/deepwork_jobs/steps/clone_remote_job.md create mode 100644 .gemini/skills/deepwork_jobs/clone_remote_job.toml create mode 100755 src/deepwork/standard_jobs/deepwork_jobs/install_remote_job.sh create mode 100644 src/deepwork/standard_jobs/deepwork_jobs/steps/clone_remote_job.md diff --git a/.claude/settings.json b/.claude/settings.json index cf4e3c4c..f37f8fb1 100644 --- a/.claude/settings.json +++ b/.claude/settings.json @@ -130,7 +130,8 @@ "Bash(deepwork:*)", "Bash(.claude/hooks/commit_job_git_commit.sh:*)", "Bash(./.deepwork/jobs/deepwork_jobs/make_new_job.sh:*)", - "WebSearch" + "WebSearch", + "Skill(deepwork_jobs.clone_remote_job)" ] }, "hooks": { diff --git a/.claude/skills/deepwork_jobs.clone_remote_job/SKILL.md b/.claude/skills/deepwork_jobs.clone_remote_job/SKILL.md new file mode 100644 index 00000000..8d3277e5 --- /dev/null +++ b/.claude/skills/deepwork_jobs.clone_remote_job/SKILL.md @@ -0,0 +1,287 @@ +--- +name: deepwork_jobs.clone_remote_job +description: "Installs a DeepWork job from a GitHub repository and guides customization. Use when adding a pre-built job from the library."--- + +# deepwork_jobs.clone_remote_job + +**Standalone skill** - can be run anytime + +> Creates and manages multi-step AI workflows. Use when defining, implementing, or improving DeepWork jobs. + + +## Instructions + +**Goal**: Installs a DeepWork job from a GitHub repository and guides customization. Use when adding a pre-built job from the library. + +# Clone Remote Job + +## Objective + +Help the user install a DeepWork job from a remote GitHub repository and customize it for their project. + +## Task + +Guide the user through cloning a remote job from the DeepWork job library (or any GitHub repository), then assist with any required customization. + +### Step 1: Understand the User's Request + +1. **Get the job URL** + - Ask the user for the GitHub URL of the job they want to install + - The URL should point to a job directory, e.g.: + - `https://github.com/Unsupervisedcom/deepwork/tree/main/library/jobs/spec_driven_development` + - If they don't have a URL, point them to the job library: `https://github.com/Unsupervisedcom/deepwork/tree/main/library/jobs` + +2. **Confirm the destination** + - Jobs are installed to `.deepwork/jobs//` + - If a job with the same name exists, warn the user it will be overwritten + +### Step 2: Run the Install Script + +Execute the `install_remote_job.sh` script: + +```bash +.deepwork/jobs/deepwork_jobs/install_remote_job.sh +``` + +**Script requirements:** +- `curl` - for downloading files +- `jq` - for parsing JSON responses from GitHub API + +If the script fails due to missing dependencies, help the user install them: +- On macOS: `brew install jq` +- On Ubuntu/Debian: `sudo apt-get install jq` +- On other systems: Guide them to https://stedolan.github.io/jq/download/ + +### Step 3: Review the Job's README + +After installation, check for a readme file in the installed job directory: + +1. **Read the readme** + - Check for `readme.md` or `README.md` in `.deepwork/jobs//` + - Look for sections about customization, configuration, or setup + +2. **Identify required customizations** + - Look for placeholders like `[docs_folder]`, `[project_name]`, etc. + - Note any environment variables or configuration needed + - Check for technology stack requirements + +### Step 4: Apply Customizations + +Work through any required customizations with the user: + +1. **Replace placeholders** + - Use find/replace to update placeholders throughout the job files + - Example: Replace `[docs_folder]` with the actual documentation directory + ```bash + # Find all occurrences + grep -r "\[docs_folder\]" .deepwork/jobs// + + # Replace throughout the job (preview first) + find .deepwork/jobs// -type f -name "*.md" -o -name "*.yml" | xargs sed -i 's/\[docs_folder\]/docs/g' + ``` + +2. **Adjust for project conventions** + - Review step instructions for any project-specific adjustments + - Update paths, naming conventions, or workflow steps as needed + +3. **Configure any required integrations** + - Set up environment variables if needed + - Configure any external services or tools + +### Step 5: Update the README + +After applying customizations: + +1. **Remove customization instructions** + - Delete or update the "REQUIRED CUSTOMIZATION" section in the readme + - The readme should now describe the job as configured for this project + +2. **Add project-specific notes** + - Document any customizations made + - Add notes about how this job fits into the project workflow + +### Step 6: Sync and Test + +1. **Run deepwork sync** + ```bash + deepwork sync + ``` + +2. **Verify the job is available** + - Check that slash commands are generated in `.claude/commands/` + - Test that the job appears in command completion + +3. **Relay reload instructions** + - If skills were regenerated, tell the user to reload their environment + - For Claude Code: "Type 'exit' then run 'claude --resume'" + +## Output Format + +After completing the installation and customization: + +``` +## Installation Summary + +**Job:** +**Source:** +**Installed to:** .deepwork/jobs// + +### Customizations Applied +- [List of customizations made] + +### Available Commands +- /. - +- /. - +... + +### Next Steps +- [Any remaining setup or first-use guidance] +``` + +## Quality Criteria + +- Job files downloaded successfully to `.deepwork/jobs//` +- README reviewed for customization requirements +- All required placeholders replaced with project-specific values +- README updated to remove/update customization instructions +- `deepwork sync` run successfully +- User informed of available slash commands +- When all criteria are met, include `✓ Quality Criteria Met` + +## Example Dialog + +``` +User: /deepwork_jobs.clone_remote_job + +Claude: I'll help you install a remote DeepWork job. + +What is the GitHub URL of the job you'd like to install? + +If you're looking for jobs to install, you can browse the job library at: +https://github.com/Unsupervisedcom/deepwork/tree/main/library/jobs + +User: https://github.com/Unsupervisedcom/deepwork/tree/main/library/jobs/spec_driven_development + +Claude: I'll install the spec_driven_development job for you. + +*Runs install_remote_job.sh script* + +The job has been installed to `.deepwork/jobs/spec_driven_development/`. + +Let me review the readme for any required customization... + +I found that this job requires customization - there's a placeholder `[docs_folder]` that needs to be replaced with your project's documentation directory. + +Where do you keep your documentation? (e.g., `docs/`, `documentation/`, or at the root) + +User: We use docs/ + +Claude: I'll replace `[docs_folder]` with `docs` throughout the job files. + +*Makes replacements* + +I've updated 4 files with the correct documentation path. Let me also update the readme to remove the customization instructions since this is now configured for your project. + +*Updates readme* + +Now let me sync the job to generate slash commands. + +*Runs deepwork sync* + +## Installation Summary + +**Job:** spec_driven_development +**Source:** https://github.com/Unsupervisedcom/deepwork/tree/main/library/jobs/spec_driven_development +**Installed to:** .deepwork/jobs/spec_driven_development/ + +### Customizations Applied +- Replaced `[docs_folder]` with `docs` in job.yml, constitution.md, plan.md +- Updated readme to remove customization instructions + +### Available Commands +- /spec_driven_development.constitution - Establish project governance principles +- /spec_driven_development.specify - Create feature specification +- /spec_driven_development.clarify - Clarify specification details +- /spec_driven_development.plan - Generate technical plan +- /spec_driven_development.tasks - Generate task breakdown +- /spec_driven_development.implement - Execute implementation + +To use the new commands, type 'exit' then run 'claude --resume'. + +✓ Quality Criteria Met +``` + + +### Job Context + +Core commands for managing DeepWork jobs. These commands help you define new multi-step +workflows, install pre-built jobs from remote repositories, and learn from running them. + +The `new_job` workflow guides you through defining and implementing a new job by +asking structured questions about your workflow, understanding each step's inputs and outputs, +reviewing the specification, and generating all necessary files. + +The `clone_remote_job` skill installs a job from a GitHub repository (like the DeepWork +job library) and guides you through any required customization for your project. + +The `learn` skill reflects on conversations where DeepWork jobs were run, identifies +confusion or inefficiencies, and improves job instructions. It also captures bespoke +learnings specific to the current run into AGENTS.md files in the working folder. + + +## Required Inputs + +**User Parameters** - Gather from user before starting: +- **github_url**: GitHub URL to the job directory (e.g., https://github.com/Unsupervisedcom/deepwork/tree/main/library/jobs/spec_driven_development) + + +## Work Branch + +Use branch format: `deepwork/deepwork_jobs-[instance]-YYYYMMDD` + +- If on a matching work branch: continue using it +- If on main/master: create new branch with `git checkout -b deepwork/deepwork_jobs-[instance]-$(date +%Y%m%d)` + +## Outputs + +**Required outputs**: +- `.deepwork/jobs/` (directory) + +## Guardrails + +- Do NOT skip prerequisite verification if this step has dependencies +- Do NOT produce partial outputs; complete all required outputs before finishing +- Do NOT proceed without required inputs; ask the user if any are missing +- Do NOT modify files outside the scope of this step's defined outputs + +## Quality Validation + +**Before completing this step, you MUST have your work reviewed against the quality criteria below.** + +Use a sub-agent (Haiku model) to review your work against these criteria: + +**Criteria (all must be satisfied)**: +1. **Script Executed**: Was install_remote_job.sh run successfully? +2. **Files Downloaded**: Were all job files downloaded to .deepwork/jobs/[job_name]/? +3. **README Reviewed**: Was the job's readme checked for customization requirements? +4. **Placeholders Replaced**: Were all required placeholders replaced with project-specific values? +5. **README Updated**: Was the readme updated to remove/update customization instructions? +6. **Sync Complete**: Has `deepwork sync` been run successfully? +7. **Commands Available**: Are the new slash commands accessible to the user? +**Review Process**: +1. Once you believe your work is complete, spawn a sub-agent using Haiku to review your work against the quality criteria above +2. The sub-agent should examine your outputs and verify each criterion is met +3. If the sub-agent identifies valid issues, fix them +4. Have the sub-agent review again until all valid feedback has been addressed +5. Only mark the step complete when the sub-agent confirms all criteria are satisfied + +## On Completion + +1. Verify outputs are created +2. Inform user: "clone_remote_job complete, outputs: .deepwork/jobs/" + +This standalone skill can be re-run anytime. + +--- + +**Reference files**: `.deepwork/jobs/deepwork_jobs/job.yml`, `.deepwork/jobs/deepwork_jobs/steps/clone_remote_job.md` \ No newline at end of file diff --git a/.claude/skills/deepwork_jobs.define/SKILL.md b/.claude/skills/deepwork_jobs.define/SKILL.md index a6ec07d3..dd3669c3 100644 --- a/.claude/skills/deepwork_jobs.define/SKILL.md +++ b/.claude/skills/deepwork_jobs.define/SKILL.md @@ -420,12 +420,15 @@ After creating the file: ### Job Context Core commands for managing DeepWork jobs. These commands help you define new multi-step -workflows and learn from running them. +workflows, install pre-built jobs from remote repositories, and learn from running them. The `new_job` workflow guides you through defining and implementing a new job by asking structured questions about your workflow, understanding each step's inputs and outputs, reviewing the specification, and generating all necessary files. +The `clone_remote_job` skill installs a job from a GitHub repository (like the DeepWork +job library) and guides you through any required customization for your project. + The `learn` skill reflects on conversations where DeepWork jobs were run, identifies confusion or inefficiencies, and improves job instructions. It also captures bespoke learnings specific to the current run into AGENTS.md files in the working folder. diff --git a/.claude/skills/deepwork_jobs.implement/SKILL.md b/.claude/skills/deepwork_jobs.implement/SKILL.md index c9510269..fc384376 100644 --- a/.claude/skills/deepwork_jobs.implement/SKILL.md +++ b/.claude/skills/deepwork_jobs.implement/SKILL.md @@ -265,12 +265,15 @@ Before marking this step complete, ensure: ### Job Context Core commands for managing DeepWork jobs. These commands help you define new multi-step -workflows and learn from running them. +workflows, install pre-built jobs from remote repositories, and learn from running them. The `new_job` workflow guides you through defining and implementing a new job by asking structured questions about your workflow, understanding each step's inputs and outputs, reviewing the specification, and generating all necessary files. +The `clone_remote_job` skill installs a job from a GitHub repository (like the DeepWork +job library) and guides you through any required customization for your project. + The `learn` skill reflects on conversations where DeepWork jobs were run, identifies confusion or inefficiencies, and improves job instructions. It also captures bespoke learnings specific to the current run into AGENTS.md files in the working folder. diff --git a/.claude/skills/deepwork_jobs.learn/SKILL.md b/.claude/skills/deepwork_jobs.learn/SKILL.md index f2db5a56..4b1fc3d0 100644 --- a/.claude/skills/deepwork_jobs.learn/SKILL.md +++ b/.claude/skills/deepwork_jobs.learn/SKILL.md @@ -377,12 +377,15 @@ Updated job instructions and created AGENTS.md with bespoke learnings. To get th ### Job Context Core commands for managing DeepWork jobs. These commands help you define new multi-step -workflows and learn from running them. +workflows, install pre-built jobs from remote repositories, and learn from running them. The `new_job` workflow guides you through defining and implementing a new job by asking structured questions about your workflow, understanding each step's inputs and outputs, reviewing the specification, and generating all necessary files. +The `clone_remote_job` skill installs a job from a GitHub repository (like the DeepWork +job library) and guides you through any required customization for your project. + The `learn` skill reflects on conversations where DeepWork jobs were run, identifies confusion or inefficiencies, and improves job instructions. It also captures bespoke learnings specific to the current run into AGENTS.md files in the working folder. diff --git a/.claude/skills/deepwork_jobs.review_job_spec/SKILL.md b/.claude/skills/deepwork_jobs.review_job_spec/SKILL.md index 99a565ef..94921aa3 100644 --- a/.claude/skills/deepwork_jobs.review_job_spec/SKILL.md +++ b/.claude/skills/deepwork_jobs.review_job_spec/SKILL.md @@ -235,12 +235,15 @@ The validated `job.yml` file at `.deepwork/jobs/[job_name]/job.yml` that passes ### Job Context Core commands for managing DeepWork jobs. These commands help you define new multi-step -workflows and learn from running them. +workflows, install pre-built jobs from remote repositories, and learn from running them. The `new_job` workflow guides you through defining and implementing a new job by asking structured questions about your workflow, understanding each step's inputs and outputs, reviewing the specification, and generating all necessary files. +The `clone_remote_job` skill installs a job from a GitHub repository (like the DeepWork +job library) and guides you through any required customization for your project. + The `learn` skill reflects on conversations where DeepWork jobs were run, identifies confusion or inefficiencies, and improves job instructions. It also captures bespoke learnings specific to the current run into AGENTS.md files in the working folder. diff --git a/.claude/skills/deepwork_jobs/SKILL.md b/.claude/skills/deepwork_jobs/SKILL.md index ec2526f5..7678b960 100644 --- a/.claude/skills/deepwork_jobs/SKILL.md +++ b/.claude/skills/deepwork_jobs/SKILL.md @@ -10,12 +10,15 @@ Creates and manages multi-step AI workflows. Use when defining, implementing, or > **CRITICAL**: Always invoke steps using the Skill tool. Never copy/paste step instructions directly. Core commands for managing DeepWork jobs. These commands help you define new multi-step -workflows and learn from running them. +workflows, install pre-built jobs from remote repositories, and learn from running them. The `new_job` workflow guides you through defining and implementing a new job by asking structured questions about your workflow, understanding each step's inputs and outputs, reviewing the specification, and generating all necessary files. +The `clone_remote_job` skill installs a job from a GitHub repository (like the DeepWork +job library) and guides you through any required customization for your project. + The `learn` skill reflects on conversations where DeepWork jobs were run, identifies confusion or inefficiencies, and improves job instructions. It also captures bespoke learnings specific to the current run into AGENTS.md files in the working folder. @@ -40,6 +43,8 @@ These skills can be run independently at any time: - **learn** - Analyzes conversation history to improve job instructions and capture learnings. Use after running a job to refine it. Command: `/deepwork_jobs.learn` +- **clone_remote_job** - Installs a DeepWork job from a GitHub repository and guides customization. Use when adding a pre-built job from the library. + Command: `/deepwork_jobs.clone_remote_job` ## Execution Instructions @@ -49,6 +54,7 @@ These skills can be run independently at any time: Parse any text following `/deepwork_jobs` to determine user intent: - "new_job" or related terms → start new_job workflow at `deepwork_jobs.define` - "learn" or related terms → run standalone skill `deepwork_jobs.learn` +- "clone_remote_job" or related terms → run standalone skill `deepwork_jobs.clone_remote_job` ### Step 2: Invoke Starting Step diff --git a/.deepwork/jobs/deepwork_jobs/install_remote_job.sh b/.deepwork/jobs/deepwork_jobs/install_remote_job.sh new file mode 100755 index 00000000..3fe541b3 --- /dev/null +++ b/.deepwork/jobs/deepwork_jobs/install_remote_job.sh @@ -0,0 +1,294 @@ +#!/usr/bin/env bash +# +# install_remote_job.sh - Install a DeepWork job from a remote GitHub repository +# +# Usage: ./install_remote_job.sh +# +# Example: +# ./install_remote_job.sh https://github.com/Unsupervisedcom/deepwork/tree/main/library/jobs/spec_driven_development +# + +set -euo pipefail + +# Color output helpers +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +BLUE='\033[0;34m' +NC='\033[0m' # No Color + +info() { + echo -e "${GREEN}[INFO]${NC} $1" +} + +warn() { + echo -e "${YELLOW}[WARN]${NC} $1" +} + +error() { + echo -e "${RED}[ERROR]${NC} $1" + exit 1 +} + +debug() { + if [[ "${DEBUG:-}" == "1" ]]; then + echo -e "${BLUE}[DEBUG]${NC} $1" + fi +} + +# Check for required commands +check_dependencies() { + local missing=() + + if ! command -v curl &> /dev/null; then + missing+=("curl") + fi + + if ! command -v jq &> /dev/null; then + missing+=("jq") + fi + + if [[ ${#missing[@]} -gt 0 ]]; then + error "Missing required commands: ${missing[*]}. Please install them and try again." + fi +} + +# Parse GitHub URL to extract owner, repo, branch, and path +# Supports formats: +# https://github.com/owner/repo/tree/branch/path/to/dir +# https://github.com/owner/repo/tree/branch +parse_github_url() { + local url="$1" + + # Remove trailing slash if present + url="${url%/}" + + # Extract components using regex + if [[ "$url" =~ ^https://github\.com/([^/]+)/([^/]+)/tree/([^/]+)(/.*)?$ ]]; then + OWNER="${BASH_REMATCH[1]}" + REPO="${BASH_REMATCH[2]}" + BRANCH="${BASH_REMATCH[3]}" + PATH_IN_REPO="${BASH_REMATCH[4]:-}" + # Remove leading slash from path + PATH_IN_REPO="${PATH_IN_REPO#/}" + else + error "Invalid GitHub URL format. Expected: https://github.com/owner/repo/tree/branch/path/to/dir" + fi + + debug "Parsed URL: owner=$OWNER, repo=$REPO, branch=$BRANCH, path=$PATH_IN_REPO" +} + +# Extract job name from the path (last component) +get_job_name() { + local path="$1" + # Get the last component of the path + local job_name="${path##*/}" + + if [[ -z "$job_name" ]]; then + error "Could not determine job name from path: $path" + fi + + # Validate job name format + if [[ ! "$job_name" =~ ^[a-z][a-z0-9_]*$ ]]; then + error "Invalid job name '$job_name'. Job names must be lowercase, start with a letter, and contain only letters, numbers, and underscores." + fi + + echo "$job_name" +} + +# Fetch directory contents from GitHub API +fetch_directory_contents() { + local owner="$1" + local repo="$2" + local branch="$3" + local path="$4" + + local api_url="https://api.github.com/repos/${owner}/${repo}/contents/${path}?ref=${branch}" + debug "Fetching: $api_url" + + local response + local http_code + + # Fetch with error handling + response=$(curl -sS -w "\n%{http_code}" "$api_url" 2>&1) || { + error "Failed to connect to GitHub API" + } + + # Extract HTTP code (last line) + http_code=$(echo "$response" | tail -n1) + # Extract body (everything except last line) + response=$(echo "$response" | sed '$d') + + if [[ "$http_code" != "200" ]]; then + if [[ "$http_code" == "404" ]]; then + error "Path not found: $path (in $owner/$repo branch $branch)" + elif [[ "$http_code" == "403" ]]; then + error "Rate limited by GitHub API. Try again later or set GITHUB_TOKEN environment variable." + else + error "GitHub API returned HTTP $http_code: $response" + fi + fi + + echo "$response" +} + +# Download a single file +download_file() { + local download_url="$1" + local dest_path="$2" + + debug "Downloading: $download_url -> $dest_path" + + # Create parent directory if needed + mkdir -p "$(dirname "$dest_path")" + + if ! curl -sS -L -o "$dest_path" "$download_url"; then + error "Failed to download: $download_url" + fi +} + +# Recursively download all files in a directory +download_directory() { + local owner="$1" + local repo="$2" + local branch="$3" + local remote_path="$4" + local local_base="$5" + local relative_path="${6:-}" + + local contents + contents=$(fetch_directory_contents "$owner" "$repo" "$branch" "$remote_path") + + # Check if contents is an array (directory) or object (single file) + local content_type + content_type=$(echo "$contents" | jq -r 'type') + + if [[ "$content_type" == "object" ]]; then + # Single file + local name download_url + name=$(echo "$contents" | jq -r '.name') + download_url=$(echo "$contents" | jq -r '.download_url') + + if [[ "$download_url" != "null" ]]; then + local dest_path="${local_base}/${relative_path}${name}" + download_file "$download_url" "$dest_path" + info " Downloaded: ${relative_path}${name}" + fi + else + # Directory listing + local items + items=$(echo "$contents" | jq -c '.[]') + + while IFS= read -r item; do + local name type download_url item_path + name=$(echo "$item" | jq -r '.name') + type=$(echo "$item" | jq -r '.type') + download_url=$(echo "$item" | jq -r '.download_url') + item_path=$(echo "$item" | jq -r '.path') + + if [[ "$type" == "file" ]]; then + local dest_path="${local_base}/${relative_path}${name}" + download_file "$download_url" "$dest_path" + info " Downloaded: ${relative_path}${name}" + elif [[ "$type" == "dir" ]]; then + # Recursively download subdirectory + mkdir -p "${local_base}/${relative_path}${name}" + download_directory "$owner" "$repo" "$branch" "$item_path" "$local_base" "${relative_path}${name}/" + fi + done <<< "$items" + fi +} + +# Main script +main() { + if [[ $# -lt 1 ]]; then + echo "Usage: $0 " + echo "" + echo "Install a DeepWork job from a remote GitHub repository." + echo "" + echo "Arguments:" + echo " github_url URL to a job directory on GitHub" + echo "" + echo "Example:" + echo " $0 https://github.com/Unsupervisedcom/deepwork/tree/main/library/jobs/spec_driven_development" + echo "" + echo "Environment variables:" + echo " GITHUB_TOKEN (optional) GitHub personal access token for higher rate limits" + echo " DEBUG=1 (optional) Enable debug output" + exit 1 + fi + + local github_url="$1" + + # Check dependencies + check_dependencies + + # Parse the GitHub URL + parse_github_url "$github_url" + + # Get job name from path + local job_name + job_name=$(get_job_name "$PATH_IN_REPO") + + info "Installing remote job: $job_name" + info " From: $OWNER/$REPO (branch: $BRANCH)" + info " Path: $PATH_IN_REPO" + + # Determine the base path - look for .deepwork directory + local base_path + if [[ -d ".deepwork/jobs" ]]; then + base_path=".deepwork/jobs" + elif [[ -d "../.deepwork/jobs" ]]; then + base_path="../.deepwork/jobs" + else + # Create from current directory + base_path=".deepwork/jobs" + mkdir -p "$base_path" + info "Created .deepwork/jobs directory" + fi + + local job_path="${base_path}/${job_name}" + + # Check if job already exists + if [[ -d "$job_path" ]]; then + warn "Job '$job_name' already exists at $job_path" + read -p "Do you want to overwrite it? [y/N] " -n 1 -r + echo + if [[ ! $REPLY =~ ^[Yy]$ ]]; then + info "Installation cancelled." + exit 0 + fi + rm -rf "$job_path" + fi + + # Create job directory + mkdir -p "$job_path" + + info "Downloading job files..." + + # Download all files from the remote directory + download_directory "$OWNER" "$REPO" "$BRANCH" "$PATH_IN_REPO" "$job_path" + + echo "" + info "Successfully installed job '$job_name' to $job_path" + echo "" + + # Check for readme and customization instructions + if [[ -f "$job_path/readme.md" ]] || [[ -f "$job_path/README.md" ]]; then + warn "This job may require customization!" + info "Please review the readme file for setup instructions:" + if [[ -f "$job_path/readme.md" ]]; then + echo " $job_path/readme.md" + else + echo " $job_path/README.md" + fi + fi + + echo "" + info "Next steps:" + echo " 1. Review the job's readme for any required customization" + echo " 2. Run 'deepwork sync' to generate slash commands" + echo " 3. Use the job with /${job_name}." +} + +main "$@" diff --git a/.deepwork/jobs/deepwork_jobs/job.yml b/.deepwork/jobs/deepwork_jobs/job.yml index 1cb38621..bc8de14a 100644 --- a/.deepwork/jobs/deepwork_jobs/job.yml +++ b/.deepwork/jobs/deepwork_jobs/job.yml @@ -1,14 +1,17 @@ name: deepwork_jobs -version: "1.0.0" +version: "1.1.0" summary: "Creates and manages multi-step AI workflows. Use when defining, implementing, or improving DeepWork jobs." description: | Core commands for managing DeepWork jobs. These commands help you define new multi-step - workflows and learn from running them. + workflows, install pre-built jobs from remote repositories, and learn from running them. The `new_job` workflow guides you through defining and implementing a new job by asking structured questions about your workflow, understanding each step's inputs and outputs, reviewing the specification, and generating all necessary files. + The `clone_remote_job` skill installs a job from a GitHub repository (like the DeepWork + job library) and guides you through any required customization for your project. + The `learn` skill reflects on conversations where DeepWork jobs were run, identifies confusion or inefficiencies, and improves job instructions. It also captures bespoke learnings specific to the current run into AGENTS.md files in the working folder. @@ -22,6 +25,8 @@ workflows: - implement changelog: + - version: "1.1.0" + changes: "Added clone_remote_job skill and install_remote_job.sh script for installing jobs from GitHub repositories" - version: "1.0.0" changes: "Added workflows section to distinguish new_job workflow (define→review_job_spec→implement) from standalone learn skill" - version: "0.1.0" @@ -133,3 +138,23 @@ steps: - "**Working Folder Correct**: Is AGENTS.md in the correct working folder for the job?" - "**Generalizable Separated**: Are generalizable improvements in instructions, not AGENTS.md?" - "**Sync Complete**: Has `deepwork sync` been run if instructions were modified?" + + - id: clone_remote_job + name: "Clone Remote Job" + description: "Installs a DeepWork job from a GitHub repository and guides customization. Use when adding a pre-built job from the library." + instructions_file: steps/clone_remote_job.md + exposed: true + inputs: + - name: github_url + description: "GitHub URL to the job directory (e.g., https://github.com/Unsupervisedcom/deepwork/tree/main/library/jobs/spec_driven_development)" + outputs: + - .deepwork/jobs/ + dependencies: [] + quality_criteria: + - "**Script Executed**: Was install_remote_job.sh run successfully?" + - "**Files Downloaded**: Were all job files downloaded to .deepwork/jobs/[job_name]/?" + - "**README Reviewed**: Was the job's readme checked for customization requirements?" + - "**Placeholders Replaced**: Were all required placeholders replaced with project-specific values?" + - "**README Updated**: Was the readme updated to remove/update customization instructions?" + - "**Sync Complete**: Has `deepwork sync` been run successfully?" + - "**Commands Available**: Are the new slash commands accessible to the user?" diff --git a/.deepwork/jobs/deepwork_jobs/steps/clone_remote_job.md b/.deepwork/jobs/deepwork_jobs/steps/clone_remote_job.md new file mode 100644 index 00000000..c2b57d23 --- /dev/null +++ b/.deepwork/jobs/deepwork_jobs/steps/clone_remote_job.md @@ -0,0 +1,197 @@ +# Clone Remote Job + +## Objective + +Help the user install a DeepWork job from a remote GitHub repository and customize it for their project. + +## Task + +Guide the user through cloning a remote job from the DeepWork job library (or any GitHub repository), then assist with any required customization. + +### Step 1: Understand the User's Request + +1. **Get the job URL** + - Ask the user for the GitHub URL of the job they want to install + - The URL should point to a job directory, e.g.: + - `https://github.com/Unsupervisedcom/deepwork/tree/main/library/jobs/spec_driven_development` + - If they don't have a URL, point them to the job library: `https://github.com/Unsupervisedcom/deepwork/tree/main/library/jobs` + +2. **Confirm the destination** + - Jobs are installed to `.deepwork/jobs//` + - If a job with the same name exists, warn the user it will be overwritten + +### Step 2: Run the Install Script + +Execute the `install_remote_job.sh` script: + +```bash +.deepwork/jobs/deepwork_jobs/install_remote_job.sh +``` + +**Script requirements:** +- `curl` - for downloading files +- `jq` - for parsing JSON responses from GitHub API + +If the script fails due to missing dependencies, help the user install them: +- On macOS: `brew install jq` +- On Ubuntu/Debian: `sudo apt-get install jq` +- On other systems: Guide them to https://stedolan.github.io/jq/download/ + +### Step 3: Review the Job's README + +After installation, check for a readme file in the installed job directory: + +1. **Read the readme** + - Check for `readme.md` or `README.md` in `.deepwork/jobs//` + - Look for sections about customization, configuration, or setup + +2. **Identify required customizations** + - Look for placeholders like `[docs_folder]`, `[project_name]`, etc. + - Note any environment variables or configuration needed + - Check for technology stack requirements + +### Step 4: Apply Customizations + +Work through any required customizations with the user: + +1. **Replace placeholders** + - Use find/replace to update placeholders throughout the job files + - Example: Replace `[docs_folder]` with the actual documentation directory + ```bash + # Find all occurrences + grep -r "\[docs_folder\]" .deepwork/jobs// + + # Replace throughout the job (preview first) + find .deepwork/jobs// -type f -name "*.md" -o -name "*.yml" | xargs sed -i 's/\[docs_folder\]/docs/g' + ``` + +2. **Adjust for project conventions** + - Review step instructions for any project-specific adjustments + - Update paths, naming conventions, or workflow steps as needed + +3. **Configure any required integrations** + - Set up environment variables if needed + - Configure any external services or tools + +### Step 5: Update the README + +After applying customizations: + +1. **Remove customization instructions** + - Delete or update the "REQUIRED CUSTOMIZATION" section in the readme + - The readme should now describe the job as configured for this project + +2. **Add project-specific notes** + - Document any customizations made + - Add notes about how this job fits into the project workflow + +### Step 6: Sync and Test + +1. **Run deepwork sync** + ```bash + deepwork sync + ``` + +2. **Verify the job is available** + - Check that slash commands are generated in `.claude/commands/` + - Test that the job appears in command completion + +3. **Relay reload instructions** + - If skills were regenerated, tell the user to reload their environment + - For Claude Code: "Type 'exit' then run 'claude --resume'" + +## Output Format + +After completing the installation and customization: + +``` +## Installation Summary + +**Job:** +**Source:** +**Installed to:** .deepwork/jobs// + +### Customizations Applied +- [List of customizations made] + +### Available Commands +- /. - +- /. - +... + +### Next Steps +- [Any remaining setup or first-use guidance] +``` + +## Quality Criteria + +- Job files downloaded successfully to `.deepwork/jobs//` +- README reviewed for customization requirements +- All required placeholders replaced with project-specific values +- README updated to remove/update customization instructions +- `deepwork sync` run successfully +- User informed of available slash commands +- When all criteria are met, include `✓ Quality Criteria Met` + +## Example Dialog + +``` +User: /deepwork_jobs.clone_remote_job + +Claude: I'll help you install a remote DeepWork job. + +What is the GitHub URL of the job you'd like to install? + +If you're looking for jobs to install, you can browse the job library at: +https://github.com/Unsupervisedcom/deepwork/tree/main/library/jobs + +User: https://github.com/Unsupervisedcom/deepwork/tree/main/library/jobs/spec_driven_development + +Claude: I'll install the spec_driven_development job for you. + +*Runs install_remote_job.sh script* + +The job has been installed to `.deepwork/jobs/spec_driven_development/`. + +Let me review the readme for any required customization... + +I found that this job requires customization - there's a placeholder `[docs_folder]` that needs to be replaced with your project's documentation directory. + +Where do you keep your documentation? (e.g., `docs/`, `documentation/`, or at the root) + +User: We use docs/ + +Claude: I'll replace `[docs_folder]` with `docs` throughout the job files. + +*Makes replacements* + +I've updated 4 files with the correct documentation path. Let me also update the readme to remove the customization instructions since this is now configured for your project. + +*Updates readme* + +Now let me sync the job to generate slash commands. + +*Runs deepwork sync* + +## Installation Summary + +**Job:** spec_driven_development +**Source:** https://github.com/Unsupervisedcom/deepwork/tree/main/library/jobs/spec_driven_development +**Installed to:** .deepwork/jobs/spec_driven_development/ + +### Customizations Applied +- Replaced `[docs_folder]` with `docs` in job.yml, constitution.md, plan.md +- Updated readme to remove customization instructions + +### Available Commands +- /spec_driven_development.constitution - Establish project governance principles +- /spec_driven_development.specify - Create feature specification +- /spec_driven_development.clarify - Clarify specification details +- /spec_driven_development.plan - Generate technical plan +- /spec_driven_development.tasks - Generate task breakdown +- /spec_driven_development.implement - Execute implementation + +To use the new commands, type 'exit' then run 'claude --resume'. + +✓ Quality Criteria Met +``` diff --git a/.gemini/skills/deepwork_jobs/clone_remote_job.toml b/.gemini/skills/deepwork_jobs/clone_remote_job.toml new file mode 100644 index 00000000..fa620d59 --- /dev/null +++ b/.gemini/skills/deepwork_jobs/clone_remote_job.toml @@ -0,0 +1,277 @@ +# deepwork_jobs:clone_remote_job +# +# Installs a DeepWork job from a GitHub repository and guides customization. Use when adding a pre-built job from the library. +# +# Generated by DeepWork - do not edit manually + +description = "Installs a DeepWork job from a GitHub repository and guides customization. Use when adding a pre-built job from the library." + +prompt = """ +# deepwork_jobs:clone_remote_job + +**Standalone command** - can be run anytime + +> Creates and manages multi-step AI workflows. Use when defining, implementing, or improving DeepWork jobs. + + +## Instructions + +**Goal**: Installs a DeepWork job from a GitHub repository and guides customization. Use when adding a pre-built job from the library. + +# Clone Remote Job + +## Objective + +Help the user install a DeepWork job from a remote GitHub repository and customize it for their project. + +## Task + +Guide the user through cloning a remote job from the DeepWork job library (or any GitHub repository), then assist with any required customization. + +### Step 1: Understand the User's Request + +1. **Get the job URL** + - Ask the user for the GitHub URL of the job they want to install + - The URL should point to a job directory, e.g.: + - `https://github.com/Unsupervisedcom/deepwork/tree/main/library/jobs/spec_driven_development` + - If they don't have a URL, point them to the job library: `https://github.com/Unsupervisedcom/deepwork/tree/main/library/jobs` + +2. **Confirm the destination** + - Jobs are installed to `.deepwork/jobs//` + - If a job with the same name exists, warn the user it will be overwritten + +### Step 2: Run the Install Script + +Execute the `install_remote_job.sh` script: + +```bash +.deepwork/jobs/deepwork_jobs/install_remote_job.sh +``` + +**Script requirements:** +- `curl` - for downloading files +- `jq` - for parsing JSON responses from GitHub API + +If the script fails due to missing dependencies, help the user install them: +- On macOS: `brew install jq` +- On Ubuntu/Debian: `sudo apt-get install jq` +- On other systems: Guide them to https://stedolan.github.io/jq/download/ + +### Step 3: Review the Job's README + +After installation, check for a readme file in the installed job directory: + +1. **Read the readme** + - Check for `readme.md` or `README.md` in `.deepwork/jobs//` + - Look for sections about customization, configuration, or setup + +2. **Identify required customizations** + - Look for placeholders like `[docs_folder]`, `[project_name]`, etc. + - Note any environment variables or configuration needed + - Check for technology stack requirements + +### Step 4: Apply Customizations + +Work through any required customizations with the user: + +1. **Replace placeholders** + - Use find/replace to update placeholders throughout the job files + - Example: Replace `[docs_folder]` with the actual documentation directory + ```bash + # Find all occurrences + grep -r "\[docs_folder\]" .deepwork/jobs// + + # Replace throughout the job (preview first) + find .deepwork/jobs// -type f -name "*.md" -o -name "*.yml" | xargs sed -i 's/\[docs_folder\]/docs/g' + ``` + +2. **Adjust for project conventions** + - Review step instructions for any project-specific adjustments + - Update paths, naming conventions, or workflow steps as needed + +3. **Configure any required integrations** + - Set up environment variables if needed + - Configure any external services or tools + +### Step 5: Update the README + +After applying customizations: + +1. **Remove customization instructions** + - Delete or update the "REQUIRED CUSTOMIZATION" section in the readme + - The readme should now describe the job as configured for this project + +2. **Add project-specific notes** + - Document any customizations made + - Add notes about how this job fits into the project workflow + +### Step 6: Sync and Test + +1. **Run deepwork sync** + ```bash + deepwork sync + ``` + +2. **Verify the job is available** + - Check that slash commands are generated in `.claude/commands/` + - Test that the job appears in command completion + +3. **Relay reload instructions** + - If skills were regenerated, tell the user to reload their environment + - For Claude Code: "Type 'exit' then run 'claude --resume'" + +## Output Format + +After completing the installation and customization: + +``` +## Installation Summary + +**Job:** +**Source:** +**Installed to:** .deepwork/jobs// + +### Customizations Applied +- [List of customizations made] + +### Available Commands +- /. - +- /. - +... + +### Next Steps +- [Any remaining setup or first-use guidance] +``` + +## Quality Criteria + +- Job files downloaded successfully to `.deepwork/jobs//` +- README reviewed for customization requirements +- All required placeholders replaced with project-specific values +- README updated to remove/update customization instructions +- `deepwork sync` run successfully +- User informed of available slash commands +- When all criteria are met, include `✓ Quality Criteria Met` + +## Example Dialog + +``` +User: /deepwork_jobs.clone_remote_job + +Claude: I'll help you install a remote DeepWork job. + +What is the GitHub URL of the job you'd like to install? + +If you're looking for jobs to install, you can browse the job library at: +https://github.com/Unsupervisedcom/deepwork/tree/main/library/jobs + +User: https://github.com/Unsupervisedcom/deepwork/tree/main/library/jobs/spec_driven_development + +Claude: I'll install the spec_driven_development job for you. + +*Runs install_remote_job.sh script* + +The job has been installed to `.deepwork/jobs/spec_driven_development/`. + +Let me review the readme for any required customization... + +I found that this job requires customization - there's a placeholder `[docs_folder]` that needs to be replaced with your project's documentation directory. + +Where do you keep your documentation? (e.g., `docs/`, `documentation/`, or at the root) + +User: We use docs/ + +Claude: I'll replace `[docs_folder]` with `docs` throughout the job files. + +*Makes replacements* + +I've updated 4 files with the correct documentation path. Let me also update the readme to remove the customization instructions since this is now configured for your project. + +*Updates readme* + +Now let me sync the job to generate slash commands. + +*Runs deepwork sync* + +## Installation Summary + +**Job:** spec_driven_development +**Source:** https://github.com/Unsupervisedcom/deepwork/tree/main/library/jobs/spec_driven_development +**Installed to:** .deepwork/jobs/spec_driven_development/ + +### Customizations Applied +- Replaced `[docs_folder]` with `docs` in job.yml, constitution.md, plan.md +- Updated readme to remove customization instructions + +### Available Commands +- /spec_driven_development.constitution - Establish project governance principles +- /spec_driven_development.specify - Create feature specification +- /spec_driven_development.clarify - Clarify specification details +- /spec_driven_development.plan - Generate technical plan +- /spec_driven_development.tasks - Generate task breakdown +- /spec_driven_development.implement - Execute implementation + +To use the new commands, type 'exit' then run 'claude --resume'. + +✓ Quality Criteria Met +``` + + +### Job Context + +Core commands for managing DeepWork jobs. These commands help you define new multi-step +workflows, install pre-built jobs from remote repositories, and learn from running them. + +The `new_job` workflow guides you through defining and implementing a new job by +asking structured questions about your workflow, understanding each step's inputs and outputs, +reviewing the specification, and generating all necessary files. + +The `clone_remote_job` skill installs a job from a GitHub repository (like the DeepWork +job library) and guides you through any required customization for your project. + +The `learn` skill reflects on conversations where DeepWork jobs were run, identifies +confusion or inefficiencies, and improves job instructions. It also captures bespoke +learnings specific to the current run into AGENTS.md files in the working folder. + + +## Required Inputs + +**User Parameters** - Gather from user before starting: +- **github_url**: GitHub URL to the job directory (e.g., https://github.com/Unsupervisedcom/deepwork/tree/main/library/jobs/spec_driven_development) + + +## Work Branch + +Use branch format: `deepwork/deepwork_jobs-[instance]-YYYYMMDD` + +- If on a matching work branch: continue using it +- If on main/master: create new branch with `git checkout -b deepwork/deepwork_jobs-[instance]-$(date +%Y%m%d)` + +## Outputs + +**Required outputs**: +- `.deepwork/jobs/` (directory) + +## Quality Validation (Manual) + +**NOTE**: Gemini CLI does not support automated validation. Manually verify criteria before completing. + +**Criteria (all must be satisfied)**: +1. **Script Executed**: Was install_remote_job.sh run successfully? +2. **Files Downloaded**: Were all job files downloaded to .deepwork/jobs/[job_name]/? +3. **README Reviewed**: Was the job's readme checked for customization requirements? +4. **Placeholders Replaced**: Were all required placeholders replaced with project-specific values? +5. **README Updated**: Was the readme updated to remove/update customization instructions? +6. **Sync Complete**: Has `deepwork sync` been run successfully? +7. **Commands Available**: Are the new slash commands accessible to the user? +## On Completion + +1. Verify outputs are created +2. Inform user: "clone_remote_job complete, outputs: .deepwork/jobs/" + +This standalone command can be re-run anytime. + +--- + +**Reference files**: `.deepwork/jobs/deepwork_jobs/job.yml`, `.deepwork/jobs/deepwork_jobs/steps/clone_remote_job.md` +""" \ No newline at end of file diff --git a/.gemini/skills/deepwork_jobs/define.toml b/.gemini/skills/deepwork_jobs/define.toml index 745062f3..25e72969 100644 --- a/.gemini/skills/deepwork_jobs/define.toml +++ b/.gemini/skills/deepwork_jobs/define.toml @@ -9,7 +9,7 @@ description = "Creates a job.yml specification by gathering workflow requirement prompt = """ # deepwork_jobs:define -**Step 1/4** in **deepwork_jobs** workflow +**Step 1/5** in **deepwork_jobs** workflow > Creates and manages multi-step AI workflows. Use when defining, implementing, or improving DeepWork jobs. @@ -420,12 +420,15 @@ After creating the file: ### Job Context Core commands for managing DeepWork jobs. These commands help you define new multi-step -workflows and learn from running them. +workflows, install pre-built jobs from remote repositories, and learn from running them. The `new_job` workflow guides you through defining and implementing a new job by asking structured questions about your workflow, understanding each step's inputs and outputs, reviewing the specification, and generating all necessary files. +The `clone_remote_job` skill installs a job from a GitHub repository (like the DeepWork +job library) and guides you through any required customization for your project. + The `learn` skill reflects on conversations where DeepWork jobs were run, identifies confusion or inefficiencies, and improves job instructions. It also captures bespoke learnings specific to the current run into AGENTS.md files in the working folder. @@ -484,7 +487,7 @@ Use branch format: `deepwork/deepwork_jobs-[instance]-YYYYMMDD` ## On Completion 1. Verify outputs are created -2. Inform user: "Step 1/4 complete, outputs: job.yml" +2. Inform user: "Step 1/5 complete, outputs: job.yml" 3. **Tell user next command**: `/deepwork_jobs:review_job_spec` --- diff --git a/.gemini/skills/deepwork_jobs/implement.toml b/.gemini/skills/deepwork_jobs/implement.toml index 582751ef..f2ab57e6 100644 --- a/.gemini/skills/deepwork_jobs/implement.toml +++ b/.gemini/skills/deepwork_jobs/implement.toml @@ -9,7 +9,7 @@ description = "Generates step instruction files and syncs slash commands from th prompt = """ # deepwork_jobs:implement -**Step 3/4** in **deepwork_jobs** workflow +**Step 3/5** in **deepwork_jobs** workflow > Creates and manages multi-step AI workflows. Use when defining, implementing, or improving DeepWork jobs. @@ -265,12 +265,15 @@ Before marking this step complete, ensure: ### Job Context Core commands for managing DeepWork jobs. These commands help you define new multi-step -workflows and learn from running them. +workflows, install pre-built jobs from remote repositories, and learn from running them. The `new_job` workflow guides you through defining and implementing a new job by asking structured questions about your workflow, understanding each step's inputs and outputs, reviewing the specification, and generating all necessary files. +The `clone_remote_job` skill installs a job from a GitHub repository (like the DeepWork +job library) and guides you through any required customization for your project. + The `learn` skill reflects on conversations where DeepWork jobs were run, identifies confusion or inefficiencies, and improves job instructions. It also captures bespoke learnings specific to the current run into AGENTS.md files in the working folder. @@ -311,7 +314,7 @@ Use branch format: `deepwork/deepwork_jobs-[instance]-YYYYMMDD` ## On Completion 1. Verify outputs are created -2. Inform user: "Step 3/4 complete, outputs: steps/" +2. Inform user: "Step 3/5 complete, outputs: steps/" 3. **Workflow complete**: All steps finished. Consider creating a PR to merge the work branch. --- diff --git a/.gemini/skills/deepwork_jobs/index.toml b/.gemini/skills/deepwork_jobs/index.toml index 6756ea88..13b14343 100644 --- a/.gemini/skills/deepwork_jobs/index.toml +++ b/.gemini/skills/deepwork_jobs/index.toml @@ -14,12 +14,15 @@ prompt = """ > **NOTE**: Gemini CLI requires manual command invocation. After each step, tell the user which command to run next. Core commands for managing DeepWork jobs. These commands help you define new multi-step -workflows and learn from running them. +workflows, install pre-built jobs from remote repositories, and learn from running them. The `new_job` workflow guides you through defining and implementing a new job by asking structured questions about your workflow, understanding each step's inputs and outputs, reviewing the specification, and generating all necessary files. +The `clone_remote_job` skill installs a job from a GitHub repository (like the DeepWork +job library) and guides you through any required customization for your project. + The `learn` skill reflects on conversations where DeepWork jobs were run, identifies confusion or inefficiencies, and improves job instructions. It also captures bespoke learnings specific to the current run into AGENTS.md files in the working folder. @@ -35,6 +38,8 @@ learnings specific to the current run into AGENTS.md files in the working folder Command: `/deepwork_jobs:implement` 4. **learn** - Analyzes conversation history to improve job instructions and capture learnings. Use after running a job to refine it. Command: `/deepwork_jobs:learn` +5. **clone_remote_job** - Installs a DeepWork job from a GitHub repository and guides customization. Use when adding a pre-built job from the library. + Command: `/deepwork_jobs:clone_remote_job` ## Execution Instructions @@ -45,6 +50,7 @@ Parse any text following `/deepwork_jobs` to determine user intent: - "review_job_spec" or related terms → start at `/deepwork_jobs:review_job_spec` - "implement" or related terms → start at `/deepwork_jobs:implement` - "learn" or related terms → start at `/deepwork_jobs:learn` +- "clone_remote_job" or related terms → start at `/deepwork_jobs:clone_remote_job` ### Step 2: Direct User to Starting Step diff --git a/.gemini/skills/deepwork_jobs/learn.toml b/.gemini/skills/deepwork_jobs/learn.toml index e4d7d9a9..b27bcd21 100644 --- a/.gemini/skills/deepwork_jobs/learn.toml +++ b/.gemini/skills/deepwork_jobs/learn.toml @@ -380,12 +380,15 @@ Updated job instructions and created AGENTS.md with bespoke learnings. To get th ### Job Context Core commands for managing DeepWork jobs. These commands help you define new multi-step -workflows and learn from running them. +workflows, install pre-built jobs from remote repositories, and learn from running them. The `new_job` workflow guides you through defining and implementing a new job by asking structured questions about your workflow, understanding each step's inputs and outputs, reviewing the specification, and generating all necessary files. +The `clone_remote_job` skill installs a job from a GitHub repository (like the DeepWork +job library) and guides you through any required customization for your project. + The `learn` skill reflects on conversations where DeepWork jobs were run, identifies confusion or inefficiencies, and improves job instructions. It also captures bespoke learnings specific to the current run into AGENTS.md files in the working folder. diff --git a/.gemini/skills/deepwork_jobs/review_job_spec.toml b/.gemini/skills/deepwork_jobs/review_job_spec.toml index 4e321d57..f95b61df 100644 --- a/.gemini/skills/deepwork_jobs/review_job_spec.toml +++ b/.gemini/skills/deepwork_jobs/review_job_spec.toml @@ -9,7 +9,7 @@ description = "Reviews job.yml against quality criteria using a sub-agent for un prompt = """ # deepwork_jobs:review_job_spec -**Step 2/4** in **deepwork_jobs** workflow +**Step 2/5** in **deepwork_jobs** workflow > Creates and manages multi-step AI workflows. Use when defining, implementing, or improving DeepWork jobs. @@ -235,12 +235,15 @@ The validated `job.yml` file at `.deepwork/jobs/[job_name]/job.yml` that passes ### Job Context Core commands for managing DeepWork jobs. These commands help you define new multi-step -workflows and learn from running them. +workflows, install pre-built jobs from remote repositories, and learn from running them. The `new_job` workflow guides you through defining and implementing a new job by asking structured questions about your workflow, understanding each step's inputs and outputs, reviewing the specification, and generating all necessary files. +The `clone_remote_job` skill installs a job from a GitHub repository (like the DeepWork +job library) and guides you through any required customization for your project. + The `learn` skill reflects on conversations where DeepWork jobs were run, identifies confusion or inefficiencies, and improves job instructions. It also captures bespoke learnings specific to the current run into AGENTS.md files in the working folder. @@ -291,7 +294,7 @@ Use branch format: `deepwork/deepwork_jobs-[instance]-YYYYMMDD` ## On Completion 1. Verify outputs are created -2. Inform user: "Step 2/4 complete, outputs: job.yml" +2. Inform user: "Step 2/5 complete, outputs: job.yml" 3. **Tell user next command**: `/deepwork_jobs:implement` --- diff --git a/CHANGELOG.md b/CHANGELOG.md index 9fbcd172..629a9e08 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] ### Added +- `clone_remote_job` skill in `deepwork_jobs` for installing jobs from GitHub repositories + - New `install_remote_job.sh` script that fetches job files from GitHub URLs + - Guides users through customization of installed jobs (placeholder replacement, README updates) + - Supports the DeepWork job library at `https://github.com/Unsupervisedcom/deepwork/tree/main/library/jobs/` - Explicit workflow definitions in job.yml for distinguishing multi-step workflows from standalone skills - New `workflows` section in job.yml with `name`, `summary`, and ordered `steps` array - Workflows are shown separately from standalone skills in generated meta-skills @@ -18,7 +22,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Changed - Skill templates now show workflow-aware progress (e.g., "new_job step 2/3 complete") - Meta-skill template reorganized to show "Workflows" and "Standalone Skills" sections separately -- Updated `deepwork_jobs` standard job to v1.0.0 with explicit `new_job` workflow +- Updated `deepwork_jobs` standard job to v1.1.0 with explicit `new_job` workflow and `clone_remote_job` skill - SessionStart hook now skips non-initial sessions (resume, compact/clear) by checking the `source` field in stdin JSON, reducing noise and redundant checks ### Fixed diff --git a/doc/architecture.md b/doc/architecture.md index cafd92c3..a7435c19 100644 --- a/doc/architecture.md +++ b/doc/architecture.md @@ -777,6 +777,7 @@ DeepWork includes a built-in job called `deepwork_jobs` for managing jobs. It pr - Creates complete job definitions through interactive Q&A, validation, and file generation **Standalone Skills** (can be run anytime): +- **`/deepwork_jobs.clone_remote_job`** - Installs a job from a GitHub repository and guides customization - **`/deepwork_jobs.learn`** - Analyzes conversations to improve job instructions and capture learnings These skills are installed automatically when you run `deepwork install`. diff --git a/src/deepwork/standard_jobs/deepwork_jobs/install_remote_job.sh b/src/deepwork/standard_jobs/deepwork_jobs/install_remote_job.sh new file mode 100755 index 00000000..3fe541b3 --- /dev/null +++ b/src/deepwork/standard_jobs/deepwork_jobs/install_remote_job.sh @@ -0,0 +1,294 @@ +#!/usr/bin/env bash +# +# install_remote_job.sh - Install a DeepWork job from a remote GitHub repository +# +# Usage: ./install_remote_job.sh +# +# Example: +# ./install_remote_job.sh https://github.com/Unsupervisedcom/deepwork/tree/main/library/jobs/spec_driven_development +# + +set -euo pipefail + +# Color output helpers +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +BLUE='\033[0;34m' +NC='\033[0m' # No Color + +info() { + echo -e "${GREEN}[INFO]${NC} $1" +} + +warn() { + echo -e "${YELLOW}[WARN]${NC} $1" +} + +error() { + echo -e "${RED}[ERROR]${NC} $1" + exit 1 +} + +debug() { + if [[ "${DEBUG:-}" == "1" ]]; then + echo -e "${BLUE}[DEBUG]${NC} $1" + fi +} + +# Check for required commands +check_dependencies() { + local missing=() + + if ! command -v curl &> /dev/null; then + missing+=("curl") + fi + + if ! command -v jq &> /dev/null; then + missing+=("jq") + fi + + if [[ ${#missing[@]} -gt 0 ]]; then + error "Missing required commands: ${missing[*]}. Please install them and try again." + fi +} + +# Parse GitHub URL to extract owner, repo, branch, and path +# Supports formats: +# https://github.com/owner/repo/tree/branch/path/to/dir +# https://github.com/owner/repo/tree/branch +parse_github_url() { + local url="$1" + + # Remove trailing slash if present + url="${url%/}" + + # Extract components using regex + if [[ "$url" =~ ^https://github\.com/([^/]+)/([^/]+)/tree/([^/]+)(/.*)?$ ]]; then + OWNER="${BASH_REMATCH[1]}" + REPO="${BASH_REMATCH[2]}" + BRANCH="${BASH_REMATCH[3]}" + PATH_IN_REPO="${BASH_REMATCH[4]:-}" + # Remove leading slash from path + PATH_IN_REPO="${PATH_IN_REPO#/}" + else + error "Invalid GitHub URL format. Expected: https://github.com/owner/repo/tree/branch/path/to/dir" + fi + + debug "Parsed URL: owner=$OWNER, repo=$REPO, branch=$BRANCH, path=$PATH_IN_REPO" +} + +# Extract job name from the path (last component) +get_job_name() { + local path="$1" + # Get the last component of the path + local job_name="${path##*/}" + + if [[ -z "$job_name" ]]; then + error "Could not determine job name from path: $path" + fi + + # Validate job name format + if [[ ! "$job_name" =~ ^[a-z][a-z0-9_]*$ ]]; then + error "Invalid job name '$job_name'. Job names must be lowercase, start with a letter, and contain only letters, numbers, and underscores." + fi + + echo "$job_name" +} + +# Fetch directory contents from GitHub API +fetch_directory_contents() { + local owner="$1" + local repo="$2" + local branch="$3" + local path="$4" + + local api_url="https://api.github.com/repos/${owner}/${repo}/contents/${path}?ref=${branch}" + debug "Fetching: $api_url" + + local response + local http_code + + # Fetch with error handling + response=$(curl -sS -w "\n%{http_code}" "$api_url" 2>&1) || { + error "Failed to connect to GitHub API" + } + + # Extract HTTP code (last line) + http_code=$(echo "$response" | tail -n1) + # Extract body (everything except last line) + response=$(echo "$response" | sed '$d') + + if [[ "$http_code" != "200" ]]; then + if [[ "$http_code" == "404" ]]; then + error "Path not found: $path (in $owner/$repo branch $branch)" + elif [[ "$http_code" == "403" ]]; then + error "Rate limited by GitHub API. Try again later or set GITHUB_TOKEN environment variable." + else + error "GitHub API returned HTTP $http_code: $response" + fi + fi + + echo "$response" +} + +# Download a single file +download_file() { + local download_url="$1" + local dest_path="$2" + + debug "Downloading: $download_url -> $dest_path" + + # Create parent directory if needed + mkdir -p "$(dirname "$dest_path")" + + if ! curl -sS -L -o "$dest_path" "$download_url"; then + error "Failed to download: $download_url" + fi +} + +# Recursively download all files in a directory +download_directory() { + local owner="$1" + local repo="$2" + local branch="$3" + local remote_path="$4" + local local_base="$5" + local relative_path="${6:-}" + + local contents + contents=$(fetch_directory_contents "$owner" "$repo" "$branch" "$remote_path") + + # Check if contents is an array (directory) or object (single file) + local content_type + content_type=$(echo "$contents" | jq -r 'type') + + if [[ "$content_type" == "object" ]]; then + # Single file + local name download_url + name=$(echo "$contents" | jq -r '.name') + download_url=$(echo "$contents" | jq -r '.download_url') + + if [[ "$download_url" != "null" ]]; then + local dest_path="${local_base}/${relative_path}${name}" + download_file "$download_url" "$dest_path" + info " Downloaded: ${relative_path}${name}" + fi + else + # Directory listing + local items + items=$(echo "$contents" | jq -c '.[]') + + while IFS= read -r item; do + local name type download_url item_path + name=$(echo "$item" | jq -r '.name') + type=$(echo "$item" | jq -r '.type') + download_url=$(echo "$item" | jq -r '.download_url') + item_path=$(echo "$item" | jq -r '.path') + + if [[ "$type" == "file" ]]; then + local dest_path="${local_base}/${relative_path}${name}" + download_file "$download_url" "$dest_path" + info " Downloaded: ${relative_path}${name}" + elif [[ "$type" == "dir" ]]; then + # Recursively download subdirectory + mkdir -p "${local_base}/${relative_path}${name}" + download_directory "$owner" "$repo" "$branch" "$item_path" "$local_base" "${relative_path}${name}/" + fi + done <<< "$items" + fi +} + +# Main script +main() { + if [[ $# -lt 1 ]]; then + echo "Usage: $0 " + echo "" + echo "Install a DeepWork job from a remote GitHub repository." + echo "" + echo "Arguments:" + echo " github_url URL to a job directory on GitHub" + echo "" + echo "Example:" + echo " $0 https://github.com/Unsupervisedcom/deepwork/tree/main/library/jobs/spec_driven_development" + echo "" + echo "Environment variables:" + echo " GITHUB_TOKEN (optional) GitHub personal access token for higher rate limits" + echo " DEBUG=1 (optional) Enable debug output" + exit 1 + fi + + local github_url="$1" + + # Check dependencies + check_dependencies + + # Parse the GitHub URL + parse_github_url "$github_url" + + # Get job name from path + local job_name + job_name=$(get_job_name "$PATH_IN_REPO") + + info "Installing remote job: $job_name" + info " From: $OWNER/$REPO (branch: $BRANCH)" + info " Path: $PATH_IN_REPO" + + # Determine the base path - look for .deepwork directory + local base_path + if [[ -d ".deepwork/jobs" ]]; then + base_path=".deepwork/jobs" + elif [[ -d "../.deepwork/jobs" ]]; then + base_path="../.deepwork/jobs" + else + # Create from current directory + base_path=".deepwork/jobs" + mkdir -p "$base_path" + info "Created .deepwork/jobs directory" + fi + + local job_path="${base_path}/${job_name}" + + # Check if job already exists + if [[ -d "$job_path" ]]; then + warn "Job '$job_name' already exists at $job_path" + read -p "Do you want to overwrite it? [y/N] " -n 1 -r + echo + if [[ ! $REPLY =~ ^[Yy]$ ]]; then + info "Installation cancelled." + exit 0 + fi + rm -rf "$job_path" + fi + + # Create job directory + mkdir -p "$job_path" + + info "Downloading job files..." + + # Download all files from the remote directory + download_directory "$OWNER" "$REPO" "$BRANCH" "$PATH_IN_REPO" "$job_path" + + echo "" + info "Successfully installed job '$job_name' to $job_path" + echo "" + + # Check for readme and customization instructions + if [[ -f "$job_path/readme.md" ]] || [[ -f "$job_path/README.md" ]]; then + warn "This job may require customization!" + info "Please review the readme file for setup instructions:" + if [[ -f "$job_path/readme.md" ]]; then + echo " $job_path/readme.md" + else + echo " $job_path/README.md" + fi + fi + + echo "" + info "Next steps:" + echo " 1. Review the job's readme for any required customization" + echo " 2. Run 'deepwork sync' to generate slash commands" + echo " 3. Use the job with /${job_name}." +} + +main "$@" diff --git a/src/deepwork/standard_jobs/deepwork_jobs/job.yml b/src/deepwork/standard_jobs/deepwork_jobs/job.yml index 1cb38621..bc8de14a 100644 --- a/src/deepwork/standard_jobs/deepwork_jobs/job.yml +++ b/src/deepwork/standard_jobs/deepwork_jobs/job.yml @@ -1,14 +1,17 @@ name: deepwork_jobs -version: "1.0.0" +version: "1.1.0" summary: "Creates and manages multi-step AI workflows. Use when defining, implementing, or improving DeepWork jobs." description: | Core commands for managing DeepWork jobs. These commands help you define new multi-step - workflows and learn from running them. + workflows, install pre-built jobs from remote repositories, and learn from running them. The `new_job` workflow guides you through defining and implementing a new job by asking structured questions about your workflow, understanding each step's inputs and outputs, reviewing the specification, and generating all necessary files. + The `clone_remote_job` skill installs a job from a GitHub repository (like the DeepWork + job library) and guides you through any required customization for your project. + The `learn` skill reflects on conversations where DeepWork jobs were run, identifies confusion or inefficiencies, and improves job instructions. It also captures bespoke learnings specific to the current run into AGENTS.md files in the working folder. @@ -22,6 +25,8 @@ workflows: - implement changelog: + - version: "1.1.0" + changes: "Added clone_remote_job skill and install_remote_job.sh script for installing jobs from GitHub repositories" - version: "1.0.0" changes: "Added workflows section to distinguish new_job workflow (define→review_job_spec→implement) from standalone learn skill" - version: "0.1.0" @@ -133,3 +138,23 @@ steps: - "**Working Folder Correct**: Is AGENTS.md in the correct working folder for the job?" - "**Generalizable Separated**: Are generalizable improvements in instructions, not AGENTS.md?" - "**Sync Complete**: Has `deepwork sync` been run if instructions were modified?" + + - id: clone_remote_job + name: "Clone Remote Job" + description: "Installs a DeepWork job from a GitHub repository and guides customization. Use when adding a pre-built job from the library." + instructions_file: steps/clone_remote_job.md + exposed: true + inputs: + - name: github_url + description: "GitHub URL to the job directory (e.g., https://github.com/Unsupervisedcom/deepwork/tree/main/library/jobs/spec_driven_development)" + outputs: + - .deepwork/jobs/ + dependencies: [] + quality_criteria: + - "**Script Executed**: Was install_remote_job.sh run successfully?" + - "**Files Downloaded**: Were all job files downloaded to .deepwork/jobs/[job_name]/?" + - "**README Reviewed**: Was the job's readme checked for customization requirements?" + - "**Placeholders Replaced**: Were all required placeholders replaced with project-specific values?" + - "**README Updated**: Was the readme updated to remove/update customization instructions?" + - "**Sync Complete**: Has `deepwork sync` been run successfully?" + - "**Commands Available**: Are the new slash commands accessible to the user?" diff --git a/src/deepwork/standard_jobs/deepwork_jobs/steps/clone_remote_job.md b/src/deepwork/standard_jobs/deepwork_jobs/steps/clone_remote_job.md new file mode 100644 index 00000000..c2b57d23 --- /dev/null +++ b/src/deepwork/standard_jobs/deepwork_jobs/steps/clone_remote_job.md @@ -0,0 +1,197 @@ +# Clone Remote Job + +## Objective + +Help the user install a DeepWork job from a remote GitHub repository and customize it for their project. + +## Task + +Guide the user through cloning a remote job from the DeepWork job library (or any GitHub repository), then assist with any required customization. + +### Step 1: Understand the User's Request + +1. **Get the job URL** + - Ask the user for the GitHub URL of the job they want to install + - The URL should point to a job directory, e.g.: + - `https://github.com/Unsupervisedcom/deepwork/tree/main/library/jobs/spec_driven_development` + - If they don't have a URL, point them to the job library: `https://github.com/Unsupervisedcom/deepwork/tree/main/library/jobs` + +2. **Confirm the destination** + - Jobs are installed to `.deepwork/jobs//` + - If a job with the same name exists, warn the user it will be overwritten + +### Step 2: Run the Install Script + +Execute the `install_remote_job.sh` script: + +```bash +.deepwork/jobs/deepwork_jobs/install_remote_job.sh +``` + +**Script requirements:** +- `curl` - for downloading files +- `jq` - for parsing JSON responses from GitHub API + +If the script fails due to missing dependencies, help the user install them: +- On macOS: `brew install jq` +- On Ubuntu/Debian: `sudo apt-get install jq` +- On other systems: Guide them to https://stedolan.github.io/jq/download/ + +### Step 3: Review the Job's README + +After installation, check for a readme file in the installed job directory: + +1. **Read the readme** + - Check for `readme.md` or `README.md` in `.deepwork/jobs//` + - Look for sections about customization, configuration, or setup + +2. **Identify required customizations** + - Look for placeholders like `[docs_folder]`, `[project_name]`, etc. + - Note any environment variables or configuration needed + - Check for technology stack requirements + +### Step 4: Apply Customizations + +Work through any required customizations with the user: + +1. **Replace placeholders** + - Use find/replace to update placeholders throughout the job files + - Example: Replace `[docs_folder]` with the actual documentation directory + ```bash + # Find all occurrences + grep -r "\[docs_folder\]" .deepwork/jobs// + + # Replace throughout the job (preview first) + find .deepwork/jobs// -type f -name "*.md" -o -name "*.yml" | xargs sed -i 's/\[docs_folder\]/docs/g' + ``` + +2. **Adjust for project conventions** + - Review step instructions for any project-specific adjustments + - Update paths, naming conventions, or workflow steps as needed + +3. **Configure any required integrations** + - Set up environment variables if needed + - Configure any external services or tools + +### Step 5: Update the README + +After applying customizations: + +1. **Remove customization instructions** + - Delete or update the "REQUIRED CUSTOMIZATION" section in the readme + - The readme should now describe the job as configured for this project + +2. **Add project-specific notes** + - Document any customizations made + - Add notes about how this job fits into the project workflow + +### Step 6: Sync and Test + +1. **Run deepwork sync** + ```bash + deepwork sync + ``` + +2. **Verify the job is available** + - Check that slash commands are generated in `.claude/commands/` + - Test that the job appears in command completion + +3. **Relay reload instructions** + - If skills were regenerated, tell the user to reload their environment + - For Claude Code: "Type 'exit' then run 'claude --resume'" + +## Output Format + +After completing the installation and customization: + +``` +## Installation Summary + +**Job:** +**Source:** +**Installed to:** .deepwork/jobs// + +### Customizations Applied +- [List of customizations made] + +### Available Commands +- /. - +- /. - +... + +### Next Steps +- [Any remaining setup or first-use guidance] +``` + +## Quality Criteria + +- Job files downloaded successfully to `.deepwork/jobs//` +- README reviewed for customization requirements +- All required placeholders replaced with project-specific values +- README updated to remove/update customization instructions +- `deepwork sync` run successfully +- User informed of available slash commands +- When all criteria are met, include `✓ Quality Criteria Met` + +## Example Dialog + +``` +User: /deepwork_jobs.clone_remote_job + +Claude: I'll help you install a remote DeepWork job. + +What is the GitHub URL of the job you'd like to install? + +If you're looking for jobs to install, you can browse the job library at: +https://github.com/Unsupervisedcom/deepwork/tree/main/library/jobs + +User: https://github.com/Unsupervisedcom/deepwork/tree/main/library/jobs/spec_driven_development + +Claude: I'll install the spec_driven_development job for you. + +*Runs install_remote_job.sh script* + +The job has been installed to `.deepwork/jobs/spec_driven_development/`. + +Let me review the readme for any required customization... + +I found that this job requires customization - there's a placeholder `[docs_folder]` that needs to be replaced with your project's documentation directory. + +Where do you keep your documentation? (e.g., `docs/`, `documentation/`, or at the root) + +User: We use docs/ + +Claude: I'll replace `[docs_folder]` with `docs` throughout the job files. + +*Makes replacements* + +I've updated 4 files with the correct documentation path. Let me also update the readme to remove the customization instructions since this is now configured for your project. + +*Updates readme* + +Now let me sync the job to generate slash commands. + +*Runs deepwork sync* + +## Installation Summary + +**Job:** spec_driven_development +**Source:** https://github.com/Unsupervisedcom/deepwork/tree/main/library/jobs/spec_driven_development +**Installed to:** .deepwork/jobs/spec_driven_development/ + +### Customizations Applied +- Replaced `[docs_folder]` with `docs` in job.yml, constitution.md, plan.md +- Updated readme to remove customization instructions + +### Available Commands +- /spec_driven_development.constitution - Establish project governance principles +- /spec_driven_development.specify - Create feature specification +- /spec_driven_development.clarify - Clarify specification details +- /spec_driven_development.plan - Generate technical plan +- /spec_driven_development.tasks - Generate task breakdown +- /spec_driven_development.implement - Execute implementation + +To use the new commands, type 'exit' then run 'claude --resume'. + +✓ Quality Criteria Met +``` From c835d01d24414dbf4924e3fbb2f76ee9fbf8952e Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 27 Jan 2026 19:35:27 +0000 Subject: [PATCH 2/3] refactor: Simplify clone_remote_job instructions - Remove redundant description text about installing jobs - Simplify Step 6 to just review .claude/skills instead of verbose reload instructions - Remove Available Commands section from output format - Update Next Steps to include workflow kick-off instructions --- .../deepwork_jobs.clone_remote_job/SKILL.md | 34 +++++-------------- .claude/skills/deepwork_jobs.define/SKILL.md | 2 +- .../skills/deepwork_jobs.implement/SKILL.md | 2 +- .claude/skills/deepwork_jobs.learn/SKILL.md | 2 +- .../deepwork_jobs.review_job_spec/SKILL.md | 2 +- .claude/skills/deepwork_jobs/SKILL.md | 2 +- .deepwork/jobs/deepwork_jobs/job.yml | 4 +-- .../deepwork_jobs/steps/clone_remote_job.md | 30 ++++------------ .../deepwork_jobs/clone_remote_job.toml | 34 +++++-------------- .gemini/skills/deepwork_jobs/define.toml | 2 +- .gemini/skills/deepwork_jobs/implement.toml | 2 +- .gemini/skills/deepwork_jobs/index.toml | 2 +- .gemini/skills/deepwork_jobs/learn.toml | 2 +- .../skills/deepwork_jobs/review_job_spec.toml | 2 +- .../standard_jobs/deepwork_jobs/job.yml | 4 +-- .../deepwork_jobs/steps/clone_remote_job.md | 30 ++++------------ 16 files changed, 46 insertions(+), 110 deletions(-) diff --git a/.claude/skills/deepwork_jobs.clone_remote_job/SKILL.md b/.claude/skills/deepwork_jobs.clone_remote_job/SKILL.md index 8d3277e5..7df079d8 100644 --- a/.claude/skills/deepwork_jobs.clone_remote_job/SKILL.md +++ b/.claude/skills/deepwork_jobs.clone_remote_job/SKILL.md @@ -100,20 +100,14 @@ After applying customizations: - Document any customizations made - Add notes about how this job fits into the project workflow -### Step 6: Sync and Test +### Step 6: Sync and Review 1. **Run deepwork sync** ```bash deepwork sync ``` -2. **Verify the job is available** - - Check that slash commands are generated in `.claude/commands/` - - Test that the job appears in command completion - -3. **Relay reload instructions** - - If skills were regenerated, tell the user to reload their environment - - For Claude Code: "Type 'exit' then run 'claude --resume'" +2. **Review the new skills** in `.claude/skills/` to make sure they make sense ## Output Format @@ -129,12 +123,8 @@ After completing the installation and customization: ### Customizations Applied - [List of customizations made] -### Available Commands -- /. - -- /. - -... - ### Next Steps +- [Instructions on how to kick off the main job workflow, e.g., "Run / to start"] - [Any remaining setup or first-use guidance] ``` @@ -145,7 +135,7 @@ After completing the installation and customization: - All required placeholders replaced with project-specific values - README updated to remove/update customization instructions - `deepwork sync` run successfully -- User informed of available slash commands +- User informed how to kick off the job workflow - When all criteria are met, include `✓ Quality Criteria Met` ## Example Dialog @@ -198,15 +188,9 @@ Now let me sync the job to generate slash commands. - Replaced `[docs_folder]` with `docs` in job.yml, constitution.md, plan.md - Updated readme to remove customization instructions -### Available Commands -- /spec_driven_development.constitution - Establish project governance principles -- /spec_driven_development.specify - Create feature specification -- /spec_driven_development.clarify - Clarify specification details -- /spec_driven_development.plan - Generate technical plan -- /spec_driven_development.tasks - Generate task breakdown -- /spec_driven_development.implement - Execute implementation - -To use the new commands, type 'exit' then run 'claude --resume'. +### Next Steps +- Run `/spec_driven_development` to start the workflow +- Type 'exit' then run 'claude --resume' to load the new skills ✓ Quality Criteria Met ``` @@ -215,7 +199,7 @@ To use the new commands, type 'exit' then run 'claude --resume'. ### Job Context Core commands for managing DeepWork jobs. These commands help you define new multi-step -workflows, install pre-built jobs from remote repositories, and learn from running them. +workflows and learn from running them. The `new_job` workflow guides you through defining and implementing a new job by asking structured questions about your workflow, understanding each step's inputs and outputs, @@ -267,7 +251,7 @@ Use a sub-agent (Haiku model) to review your work against these criteria: 4. **Placeholders Replaced**: Were all required placeholders replaced with project-specific values? 5. **README Updated**: Was the readme updated to remove/update customization instructions? 6. **Sync Complete**: Has `deepwork sync` been run successfully? -7. **Commands Available**: Are the new slash commands accessible to the user? +7. **Workflow Instructions**: Was the user informed how to kick off the job workflow? **Review Process**: 1. Once you believe your work is complete, spawn a sub-agent using Haiku to review your work against the quality criteria above 2. The sub-agent should examine your outputs and verify each criterion is met diff --git a/.claude/skills/deepwork_jobs.define/SKILL.md b/.claude/skills/deepwork_jobs.define/SKILL.md index dd3669c3..b93304b1 100644 --- a/.claude/skills/deepwork_jobs.define/SKILL.md +++ b/.claude/skills/deepwork_jobs.define/SKILL.md @@ -420,7 +420,7 @@ After creating the file: ### Job Context Core commands for managing DeepWork jobs. These commands help you define new multi-step -workflows, install pre-built jobs from remote repositories, and learn from running them. +workflows and learn from running them. The `new_job` workflow guides you through defining and implementing a new job by asking structured questions about your workflow, understanding each step's inputs and outputs, diff --git a/.claude/skills/deepwork_jobs.implement/SKILL.md b/.claude/skills/deepwork_jobs.implement/SKILL.md index fc384376..c23ef44c 100644 --- a/.claude/skills/deepwork_jobs.implement/SKILL.md +++ b/.claude/skills/deepwork_jobs.implement/SKILL.md @@ -265,7 +265,7 @@ Before marking this step complete, ensure: ### Job Context Core commands for managing DeepWork jobs. These commands help you define new multi-step -workflows, install pre-built jobs from remote repositories, and learn from running them. +workflows and learn from running them. The `new_job` workflow guides you through defining and implementing a new job by asking structured questions about your workflow, understanding each step's inputs and outputs, diff --git a/.claude/skills/deepwork_jobs.learn/SKILL.md b/.claude/skills/deepwork_jobs.learn/SKILL.md index 4b1fc3d0..9a522ee2 100644 --- a/.claude/skills/deepwork_jobs.learn/SKILL.md +++ b/.claude/skills/deepwork_jobs.learn/SKILL.md @@ -377,7 +377,7 @@ Updated job instructions and created AGENTS.md with bespoke learnings. To get th ### Job Context Core commands for managing DeepWork jobs. These commands help you define new multi-step -workflows, install pre-built jobs from remote repositories, and learn from running them. +workflows and learn from running them. The `new_job` workflow guides you through defining and implementing a new job by asking structured questions about your workflow, understanding each step's inputs and outputs, diff --git a/.claude/skills/deepwork_jobs.review_job_spec/SKILL.md b/.claude/skills/deepwork_jobs.review_job_spec/SKILL.md index 94921aa3..b9c6de0f 100644 --- a/.claude/skills/deepwork_jobs.review_job_spec/SKILL.md +++ b/.claude/skills/deepwork_jobs.review_job_spec/SKILL.md @@ -235,7 +235,7 @@ The validated `job.yml` file at `.deepwork/jobs/[job_name]/job.yml` that passes ### Job Context Core commands for managing DeepWork jobs. These commands help you define new multi-step -workflows, install pre-built jobs from remote repositories, and learn from running them. +workflows and learn from running them. The `new_job` workflow guides you through defining and implementing a new job by asking structured questions about your workflow, understanding each step's inputs and outputs, diff --git a/.claude/skills/deepwork_jobs/SKILL.md b/.claude/skills/deepwork_jobs/SKILL.md index 7678b960..57125b98 100644 --- a/.claude/skills/deepwork_jobs/SKILL.md +++ b/.claude/skills/deepwork_jobs/SKILL.md @@ -10,7 +10,7 @@ Creates and manages multi-step AI workflows. Use when defining, implementing, or > **CRITICAL**: Always invoke steps using the Skill tool. Never copy/paste step instructions directly. Core commands for managing DeepWork jobs. These commands help you define new multi-step -workflows, install pre-built jobs from remote repositories, and learn from running them. +workflows and learn from running them. The `new_job` workflow guides you through defining and implementing a new job by asking structured questions about your workflow, understanding each step's inputs and outputs, diff --git a/.deepwork/jobs/deepwork_jobs/job.yml b/.deepwork/jobs/deepwork_jobs/job.yml index bc8de14a..a41026af 100644 --- a/.deepwork/jobs/deepwork_jobs/job.yml +++ b/.deepwork/jobs/deepwork_jobs/job.yml @@ -3,7 +3,7 @@ version: "1.1.0" summary: "Creates and manages multi-step AI workflows. Use when defining, implementing, or improving DeepWork jobs." description: | Core commands for managing DeepWork jobs. These commands help you define new multi-step - workflows, install pre-built jobs from remote repositories, and learn from running them. + workflows and learn from running them. The `new_job` workflow guides you through defining and implementing a new job by asking structured questions about your workflow, understanding each step's inputs and outputs, @@ -157,4 +157,4 @@ steps: - "**Placeholders Replaced**: Were all required placeholders replaced with project-specific values?" - "**README Updated**: Was the readme updated to remove/update customization instructions?" - "**Sync Complete**: Has `deepwork sync` been run successfully?" - - "**Commands Available**: Are the new slash commands accessible to the user?" + - "**Workflow Instructions**: Was the user informed how to kick off the job workflow?" diff --git a/.deepwork/jobs/deepwork_jobs/steps/clone_remote_job.md b/.deepwork/jobs/deepwork_jobs/steps/clone_remote_job.md index c2b57d23..1d2719ae 100644 --- a/.deepwork/jobs/deepwork_jobs/steps/clone_remote_job.md +++ b/.deepwork/jobs/deepwork_jobs/steps/clone_remote_job.md @@ -85,20 +85,14 @@ After applying customizations: - Document any customizations made - Add notes about how this job fits into the project workflow -### Step 6: Sync and Test +### Step 6: Sync and Review 1. **Run deepwork sync** ```bash deepwork sync ``` -2. **Verify the job is available** - - Check that slash commands are generated in `.claude/commands/` - - Test that the job appears in command completion - -3. **Relay reload instructions** - - If skills were regenerated, tell the user to reload their environment - - For Claude Code: "Type 'exit' then run 'claude --resume'" +2. **Review the new skills** in `.claude/skills/` to make sure they make sense ## Output Format @@ -114,12 +108,8 @@ After completing the installation and customization: ### Customizations Applied - [List of customizations made] -### Available Commands -- /. - -- /. - -... - ### Next Steps +- [Instructions on how to kick off the main job workflow, e.g., "Run / to start"] - [Any remaining setup or first-use guidance] ``` @@ -130,7 +120,7 @@ After completing the installation and customization: - All required placeholders replaced with project-specific values - README updated to remove/update customization instructions - `deepwork sync` run successfully -- User informed of available slash commands +- User informed how to kick off the job workflow - When all criteria are met, include `✓ Quality Criteria Met` ## Example Dialog @@ -183,15 +173,9 @@ Now let me sync the job to generate slash commands. - Replaced `[docs_folder]` with `docs` in job.yml, constitution.md, plan.md - Updated readme to remove customization instructions -### Available Commands -- /spec_driven_development.constitution - Establish project governance principles -- /spec_driven_development.specify - Create feature specification -- /spec_driven_development.clarify - Clarify specification details -- /spec_driven_development.plan - Generate technical plan -- /spec_driven_development.tasks - Generate task breakdown -- /spec_driven_development.implement - Execute implementation - -To use the new commands, type 'exit' then run 'claude --resume'. +### Next Steps +- Run `/spec_driven_development` to start the workflow +- Type 'exit' then run 'claude --resume' to load the new skills ✓ Quality Criteria Met ``` diff --git a/.gemini/skills/deepwork_jobs/clone_remote_job.toml b/.gemini/skills/deepwork_jobs/clone_remote_job.toml index fa620d59..e8f1f146 100644 --- a/.gemini/skills/deepwork_jobs/clone_remote_job.toml +++ b/.gemini/skills/deepwork_jobs/clone_remote_job.toml @@ -105,20 +105,14 @@ After applying customizations: - Document any customizations made - Add notes about how this job fits into the project workflow -### Step 6: Sync and Test +### Step 6: Sync and Review 1. **Run deepwork sync** ```bash deepwork sync ``` -2. **Verify the job is available** - - Check that slash commands are generated in `.claude/commands/` - - Test that the job appears in command completion - -3. **Relay reload instructions** - - If skills were regenerated, tell the user to reload their environment - - For Claude Code: "Type 'exit' then run 'claude --resume'" +2. **Review the new skills** in `.claude/skills/` to make sure they make sense ## Output Format @@ -134,12 +128,8 @@ After completing the installation and customization: ### Customizations Applied - [List of customizations made] -### Available Commands -- /. - -- /. - -... - ### Next Steps +- [Instructions on how to kick off the main job workflow, e.g., "Run / to start"] - [Any remaining setup or first-use guidance] ``` @@ -150,7 +140,7 @@ After completing the installation and customization: - All required placeholders replaced with project-specific values - README updated to remove/update customization instructions - `deepwork sync` run successfully -- User informed of available slash commands +- User informed how to kick off the job workflow - When all criteria are met, include `✓ Quality Criteria Met` ## Example Dialog @@ -203,15 +193,9 @@ Now let me sync the job to generate slash commands. - Replaced `[docs_folder]` with `docs` in job.yml, constitution.md, plan.md - Updated readme to remove customization instructions -### Available Commands -- /spec_driven_development.constitution - Establish project governance principles -- /spec_driven_development.specify - Create feature specification -- /spec_driven_development.clarify - Clarify specification details -- /spec_driven_development.plan - Generate technical plan -- /spec_driven_development.tasks - Generate task breakdown -- /spec_driven_development.implement - Execute implementation - -To use the new commands, type 'exit' then run 'claude --resume'. +### Next Steps +- Run `/spec_driven_development` to start the workflow +- Type 'exit' then run 'claude --resume' to load the new skills ✓ Quality Criteria Met ``` @@ -220,7 +204,7 @@ To use the new commands, type 'exit' then run 'claude --resume'. ### Job Context Core commands for managing DeepWork jobs. These commands help you define new multi-step -workflows, install pre-built jobs from remote repositories, and learn from running them. +workflows and learn from running them. The `new_job` workflow guides you through defining and implementing a new job by asking structured questions about your workflow, understanding each step's inputs and outputs, @@ -263,7 +247,7 @@ Use branch format: `deepwork/deepwork_jobs-[instance]-YYYYMMDD` 4. **Placeholders Replaced**: Were all required placeholders replaced with project-specific values? 5. **README Updated**: Was the readme updated to remove/update customization instructions? 6. **Sync Complete**: Has `deepwork sync` been run successfully? -7. **Commands Available**: Are the new slash commands accessible to the user? +7. **Workflow Instructions**: Was the user informed how to kick off the job workflow? ## On Completion 1. Verify outputs are created diff --git a/.gemini/skills/deepwork_jobs/define.toml b/.gemini/skills/deepwork_jobs/define.toml index 25e72969..83ce1dcc 100644 --- a/.gemini/skills/deepwork_jobs/define.toml +++ b/.gemini/skills/deepwork_jobs/define.toml @@ -420,7 +420,7 @@ After creating the file: ### Job Context Core commands for managing DeepWork jobs. These commands help you define new multi-step -workflows, install pre-built jobs from remote repositories, and learn from running them. +workflows and learn from running them. The `new_job` workflow guides you through defining and implementing a new job by asking structured questions about your workflow, understanding each step's inputs and outputs, diff --git a/.gemini/skills/deepwork_jobs/implement.toml b/.gemini/skills/deepwork_jobs/implement.toml index f2ab57e6..aea6261b 100644 --- a/.gemini/skills/deepwork_jobs/implement.toml +++ b/.gemini/skills/deepwork_jobs/implement.toml @@ -265,7 +265,7 @@ Before marking this step complete, ensure: ### Job Context Core commands for managing DeepWork jobs. These commands help you define new multi-step -workflows, install pre-built jobs from remote repositories, and learn from running them. +workflows and learn from running them. The `new_job` workflow guides you through defining and implementing a new job by asking structured questions about your workflow, understanding each step's inputs and outputs, diff --git a/.gemini/skills/deepwork_jobs/index.toml b/.gemini/skills/deepwork_jobs/index.toml index 13b14343..b09a4aee 100644 --- a/.gemini/skills/deepwork_jobs/index.toml +++ b/.gemini/skills/deepwork_jobs/index.toml @@ -14,7 +14,7 @@ prompt = """ > **NOTE**: Gemini CLI requires manual command invocation. After each step, tell the user which command to run next. Core commands for managing DeepWork jobs. These commands help you define new multi-step -workflows, install pre-built jobs from remote repositories, and learn from running them. +workflows and learn from running them. The `new_job` workflow guides you through defining and implementing a new job by asking structured questions about your workflow, understanding each step's inputs and outputs, diff --git a/.gemini/skills/deepwork_jobs/learn.toml b/.gemini/skills/deepwork_jobs/learn.toml index b27bcd21..a6ba0de7 100644 --- a/.gemini/skills/deepwork_jobs/learn.toml +++ b/.gemini/skills/deepwork_jobs/learn.toml @@ -380,7 +380,7 @@ Updated job instructions and created AGENTS.md with bespoke learnings. To get th ### Job Context Core commands for managing DeepWork jobs. These commands help you define new multi-step -workflows, install pre-built jobs from remote repositories, and learn from running them. +workflows and learn from running them. The `new_job` workflow guides you through defining and implementing a new job by asking structured questions about your workflow, understanding each step's inputs and outputs, diff --git a/.gemini/skills/deepwork_jobs/review_job_spec.toml b/.gemini/skills/deepwork_jobs/review_job_spec.toml index f95b61df..67484cf7 100644 --- a/.gemini/skills/deepwork_jobs/review_job_spec.toml +++ b/.gemini/skills/deepwork_jobs/review_job_spec.toml @@ -235,7 +235,7 @@ The validated `job.yml` file at `.deepwork/jobs/[job_name]/job.yml` that passes ### Job Context Core commands for managing DeepWork jobs. These commands help you define new multi-step -workflows, install pre-built jobs from remote repositories, and learn from running them. +workflows and learn from running them. The `new_job` workflow guides you through defining and implementing a new job by asking structured questions about your workflow, understanding each step's inputs and outputs, diff --git a/src/deepwork/standard_jobs/deepwork_jobs/job.yml b/src/deepwork/standard_jobs/deepwork_jobs/job.yml index bc8de14a..a41026af 100644 --- a/src/deepwork/standard_jobs/deepwork_jobs/job.yml +++ b/src/deepwork/standard_jobs/deepwork_jobs/job.yml @@ -3,7 +3,7 @@ version: "1.1.0" summary: "Creates and manages multi-step AI workflows. Use when defining, implementing, or improving DeepWork jobs." description: | Core commands for managing DeepWork jobs. These commands help you define new multi-step - workflows, install pre-built jobs from remote repositories, and learn from running them. + workflows and learn from running them. The `new_job` workflow guides you through defining and implementing a new job by asking structured questions about your workflow, understanding each step's inputs and outputs, @@ -157,4 +157,4 @@ steps: - "**Placeholders Replaced**: Were all required placeholders replaced with project-specific values?" - "**README Updated**: Was the readme updated to remove/update customization instructions?" - "**Sync Complete**: Has `deepwork sync` been run successfully?" - - "**Commands Available**: Are the new slash commands accessible to the user?" + - "**Workflow Instructions**: Was the user informed how to kick off the job workflow?" diff --git a/src/deepwork/standard_jobs/deepwork_jobs/steps/clone_remote_job.md b/src/deepwork/standard_jobs/deepwork_jobs/steps/clone_remote_job.md index c2b57d23..1d2719ae 100644 --- a/src/deepwork/standard_jobs/deepwork_jobs/steps/clone_remote_job.md +++ b/src/deepwork/standard_jobs/deepwork_jobs/steps/clone_remote_job.md @@ -85,20 +85,14 @@ After applying customizations: - Document any customizations made - Add notes about how this job fits into the project workflow -### Step 6: Sync and Test +### Step 6: Sync and Review 1. **Run deepwork sync** ```bash deepwork sync ``` -2. **Verify the job is available** - - Check that slash commands are generated in `.claude/commands/` - - Test that the job appears in command completion - -3. **Relay reload instructions** - - If skills were regenerated, tell the user to reload their environment - - For Claude Code: "Type 'exit' then run 'claude --resume'" +2. **Review the new skills** in `.claude/skills/` to make sure they make sense ## Output Format @@ -114,12 +108,8 @@ After completing the installation and customization: ### Customizations Applied - [List of customizations made] -### Available Commands -- /. - -- /. - -... - ### Next Steps +- [Instructions on how to kick off the main job workflow, e.g., "Run / to start"] - [Any remaining setup or first-use guidance] ``` @@ -130,7 +120,7 @@ After completing the installation and customization: - All required placeholders replaced with project-specific values - README updated to remove/update customization instructions - `deepwork sync` run successfully -- User informed of available slash commands +- User informed how to kick off the job workflow - When all criteria are met, include `✓ Quality Criteria Met` ## Example Dialog @@ -183,15 +173,9 @@ Now let me sync the job to generate slash commands. - Replaced `[docs_folder]` with `docs` in job.yml, constitution.md, plan.md - Updated readme to remove customization instructions -### Available Commands -- /spec_driven_development.constitution - Establish project governance principles -- /spec_driven_development.specify - Create feature specification -- /spec_driven_development.clarify - Clarify specification details -- /spec_driven_development.plan - Generate technical plan -- /spec_driven_development.tasks - Generate task breakdown -- /spec_driven_development.implement - Execute implementation - -To use the new commands, type 'exit' then run 'claude --resume'. +### Next Steps +- Run `/spec_driven_development` to start the workflow +- Type 'exit' then run 'claude --resume' to load the new skills ✓ Quality Criteria Met ``` From d28a2f35445df5edafd2da5f11d3e0e8ada0fa88 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 27 Jan 2026 19:35:50 +0000 Subject: [PATCH 3/3] fix: Set clone_remote_job exposed to false --- .claude/skills/deepwork_jobs.clone_remote_job/SKILL.md | 2 +- .deepwork/jobs/deepwork_jobs/job.yml | 2 +- src/deepwork/standard_jobs/deepwork_jobs/job.yml | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.claude/skills/deepwork_jobs.clone_remote_job/SKILL.md b/.claude/skills/deepwork_jobs.clone_remote_job/SKILL.md index 7df079d8..48879e14 100644 --- a/.claude/skills/deepwork_jobs.clone_remote_job/SKILL.md +++ b/.claude/skills/deepwork_jobs.clone_remote_job/SKILL.md @@ -1,6 +1,6 @@ --- name: deepwork_jobs.clone_remote_job -description: "Installs a DeepWork job from a GitHub repository and guides customization. Use when adding a pre-built job from the library."--- +description: "Installs a DeepWork job from a GitHub repository and guides customization. Use when adding a pre-built job from the library."user-invocable: false--- # deepwork_jobs.clone_remote_job diff --git a/.deepwork/jobs/deepwork_jobs/job.yml b/.deepwork/jobs/deepwork_jobs/job.yml index a41026af..29d03891 100644 --- a/.deepwork/jobs/deepwork_jobs/job.yml +++ b/.deepwork/jobs/deepwork_jobs/job.yml @@ -143,7 +143,7 @@ steps: name: "Clone Remote Job" description: "Installs a DeepWork job from a GitHub repository and guides customization. Use when adding a pre-built job from the library." instructions_file: steps/clone_remote_job.md - exposed: true + exposed: false inputs: - name: github_url description: "GitHub URL to the job directory (e.g., https://github.com/Unsupervisedcom/deepwork/tree/main/library/jobs/spec_driven_development)" diff --git a/src/deepwork/standard_jobs/deepwork_jobs/job.yml b/src/deepwork/standard_jobs/deepwork_jobs/job.yml index a41026af..29d03891 100644 --- a/src/deepwork/standard_jobs/deepwork_jobs/job.yml +++ b/src/deepwork/standard_jobs/deepwork_jobs/job.yml @@ -143,7 +143,7 @@ steps: name: "Clone Remote Job" description: "Installs a DeepWork job from a GitHub repository and guides customization. Use when adding a pre-built job from the library." instructions_file: steps/clone_remote_job.md - exposed: true + exposed: false inputs: - name: github_url description: "GitHub URL to the job directory (e.g., https://github.com/Unsupervisedcom/deepwork/tree/main/library/jobs/spec_driven_development)"