Add Claude Code plugin architecture with namespaced skills and bundled hooks

.claude-plugin/plugin.json

@@ -0,0 +1,19 @@
+{
+  "name": "deepwork",
+  "version": "0.5.2",
+  "description": "Framework for enabling AI agents to perform complex, multi-step work tasks",
+  "author": "DeepWork Contributors",
+  "homepage": "https://github.com/Unsupervisedcom/deepwork",
+  "license": "Business Source License 1.1",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Unsupervisedcom/deepwork"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "workflow",
+    "automation",
+    "multi-step"
+  ]
+}

AGENTS.md

@@ -2,6 +2,40 @@
 
 This file contains critical instructions for AI agents working on this codebase.
 
+## Claude Code Plugin Architecture
+
+**IMPORTANT**: Claude Code has retired the separate "commands" concept. Skills are now directly invocable with slash commands (e.g., `/plugin-name:skill-name`). 
+
+### Plugin Structure
+
+DeepWork is distributed as a Claude Code plugin with the following structure:
+
+```
+.claude-plugin/
+└── plugin.json              # Plugin manifest
+
+skills/
+├── install/SKILL.md         # /deepwork:install
+└── sync/SKILL.md            # /deepwork:sync
+
+hooks/
+└── hooks.json               # Event hooks configuration
+```
+
+### Skills vs Commands
+
+- **Previous approach**: Separate `commands/` and `skills/` directories where commands were user-invocable and skills were agent-invocable
+- **Current approach**: Only `skills/` directory, where all skills can be both user-invoked with slash commands AND automatically invoked by Claude based on context
+- Skills are invoked as `/deepwork:skill-name` (e.g., `/deepwork:install`, `/deepwork:sync`)
+
+### When Creating Plugin Skills
+
+- Place all skills in `skills/[skill-name]/SKILL.md`
+- Use YAML frontmatter with `name` and `description`
+- Skills will be namespaced as `/deepwork:skill-name`
+- Claude can invoke them automatically OR users can invoke them with slash commands
+- Do NOT create a separate `commands/` directory
+
 ## CRITICAL: Job Type Classification
 
 When creating or modifying jobs in this repository, you MUST understand which type of job you are working with. There are exactly **three types of jobs**, each with a specific location and purpose.

CHANGELOG.md

@@ -5,6 +5,20 @@ All notable changes to DeepWork will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+- Claude Code plugin structure with `.claude-plugin/plugin.json` manifest
+- Plugin skills: `/deepwork:install` and `/deepwork:sync` (invocable by users and automatically by Claude)
+- Plugin hooks configuration in `hooks/hooks.json`
+- Comprehensive PLUGIN.md documentation for plugin usage
+- AGENTS.md section documenting Claude Code plugin architecture
+
+### Changed
+- **Architecture**: Removed separate `commands/` directory following Claude Code's retirement of commands in favor of skills
+- Skills in `skills/` directory now serve dual purpose: user-invocable with slash commands AND automatic invocation by Claude
+- Documentation updated to reflect unified skill approach
+
 ## [0.5.2] - 2026-01-22
 
 ### Fixed

PLUGIN.md

@@ -0,0 +1,180 @@
+# DeepWork Claude Code Plugin
+
+This directory contains the Claude Code plugin distribution for DeepWork.
+
+## About
+
+DeepWork is a framework for enabling AI agents to perform complex, multi-step work tasks. This plugin provides seamless integration with Claude Code through namespaced skills and automated hooks.
+
+## Installation
+
+### Using Plugin Directory Flag (Development/Testing)
+
+```bash
+claude --plugin-dir /path/to/deepwork
+```
+
+### From GitHub Repository
+
+```bash
+# Install from GitHub
+claude plugin install https://github.com/Unsupervisedcom/deepwork
+```
+
+### From Local Clone
+
+```bash
+# Clone the repository
+git clone https://github.com/Unsupervisedcom/deepwork
+cd deepwork
+
+# Install as plugin
+claude plugin install .
+```
+
+## Plugin Structure
+
+```
+deepwork/
+├── .claude-plugin/
+│   └── plugin.json         # Plugin manifest
+├── skills/
+│   ├── install/SKILL.md    # /deepwork:install skill
+│   └── sync/SKILL.md       # /deepwork:sync skill
+└── hooks/
+    └── hooks.json          # Event hooks configuration
+```
+
+## Available Skills
+
+After installation, the following skills are available and can be invoked with slash commands:
+
+### `/deepwork:install`
+Install DeepWork in a project. Adds AI platform support and syncs commands for configured platforms.
+
+**Usage:**
+```
+/deepwork:install
+```
+
+This will:
+- Check for Git repository
+- Auto-detect available AI platforms
+- Create `.deepwork/` directory structure
+- Install core job definitions
+- Generate platform-specific skills
+- Configure hooks for rules enforcement
+
+### `/deepwork:sync`
+Sync DeepWork job definitions to platform-specific skills.
+
+**Usage:**
+```
+/deepwork:sync
+```
+
+This will:
+- Read configuration from `.deepwork/config.yml`
+- Scan all jobs in `.deepwork/jobs/`
+- Generate skills for each configured platform
+- Update hooks in platform settings
+
+## Hooks
+
+The plugin automatically configures the following hooks:
+
+- **SessionStart**: Version check
+- **UserPromptSubmit**: Rules queue management
+- **Stop/SubagentStop**: Rules validation
+
+## Requirements
+
+- Python 3.11 or higher
+- Git repository
+- DeepWork CLI tool installed (`pip install deepwork`)
+
+## Prerequisites
+
+Before using the plugin, install the DeepWork CLI tool:
+
+```bash
+# Using pipx (recommended)
+pipx install deepwork
+
+# Or using pip
+pip install deepwork
+
+# Or using uv
+uv tool install deepwork
+```
+
+## Next Steps
+
+1. Use `/deepwork:install` to set up DeepWork in your project
+2. Define your first job with `/deepwork_jobs.define`
+3. Implement the job with `/deepwork_jobs.implement`
+4. Run job steps with `/your_job_name.step_name`
+
+## Documentation
+
+- [Main README](../README.md)
+- [Architecture](../doc/architecture.md)
+- [Contributing](../CONTRIBUTING.md)
+- [License](../LICENSE.md)
+
+## Support
+
+- Issues: https://github.com/Unsupervisedcom/deepwork/issues
+- Documentation: https://github.com/Unsupervisedcom/deepwork#readme
+
+## License
+
+Business Source License 1.1 (BSL 1.1)
+
+See [LICENSE.md](../LICENSE.md) for details.
+
+## Testing the Plugin Locally
+
+To test the plugin structure before distribution:
+
+```bash
+# From the DeepWork repository root
+claude --plugin-dir /path/to/deepwork
+
+# In Claude Code, test the skills with slash commands:
+/deepwork:install
+/deepwork:sync
+```
+
+You should see the skills available with the `deepwork:` namespace prefix.
+
+## Plugin Development Notes
+
+### Directory Structure Requirements
+
+Claude Code plugins must follow this structure:
+- `.claude-plugin/plugin.json` (required) - Plugin manifest
+- `skills/` (optional) - Skills invocable with slash commands and by Claude automatically
+- `hooks/` (optional) - Event hooks configuration
+- `.mcp.json` (optional) - MCP server configurations
+- `.lsp.json` (optional) - LSP server configurations
+
+**Note**: Claude Code has retired the separate `commands/` directory. Skills now serve both purposes - they can be invoked by users with slash commands (e.g., `/deepwork:install`) AND automatically by Claude based on context.
+
+### Skill Files
+
+Skill files in `skills/[name]/SKILL.md`:
+- Have YAML frontmatter with `name` and `description`
+- Are invoked as `/plugin-name:skill-name` by users
+- Can also be invoked automatically by Claude based on context
+- Should include clear usage guidelines and examples
+
+### Hooks Configuration
+
+The `hooks/hooks.json` file configures event handlers:
+- **SessionStart**: Run when Claude Code session begins
+- **UserPromptSubmit**: Run when user submits a prompt
+- **Stop/SubagentStop**: Run when agent completes a task
+- **PreToolUse**: Run before tool invocation
+- **PostToolUse**: Run after tool invocation
+

README.md

@@ -18,6 +18,19 @@ DeepWork is a tool for defining and executing multi-step workflows with AI codin
 > **Tip:** New to DeepWork? Claude Code has the most complete feature support, including quality validation hooks and automated rules. For browser automation, Claude in Chrome (Anthropic's browser extension) works well with DeepWork workflows.
 
 ## Easy Installation
+
+### Option 1: Claude Code Plugin (Recommended)
+
+For Claude Code users, install DeepWork as a plugin:
+
+```bash
+claude plugin install https://github.com/Unsupervisedcom/deepwork
+```
+
+Then use `/deepwork:install` to set up your project.
+
+### Option 2: CLI Tool Installation
+
 In your Agent CLI (ex. `claude`), ask:
 
 ```
@@ -26,7 +39,6 @@ Please fully install https://pypi.org/project/deepwork/ and make sure you see th
 
 ## Installation Details
 
-
 **Agents**: - be sure to perform all the steps, not just the package install.
 
 ### Prerequisites
@@ -201,6 +213,19 @@ your-project/
 
 **Note**: Work outputs are created on dedicated Git branches (e.g., `deepwork/job_name-instance-date`), not in a separate directory.
 
+## Plugin Distribution
+
+DeepWork is available as a Claude Code plugin for seamless integration:
+
+**Plugin Structure**:
+- `.claude-plugin/plugin.json` - Plugin manifest with metadata
+- `skills/` - Skills invocable with `/deepwork:install`, `/deepwork:sync` and automatically by Claude
+- `hooks/` - Event hooks configuration
+
+**Note**: Claude Code has retired the separate `commands/` directory. Skills now serve both purposes - user-invocable with slash commands AND automatically invokable by Claude.
+
+**Installation**: See [PLUGIN.md](PLUGIN.md) for plugin-specific documentation.
+
 ## Documentation
 
 - **[Architecture](doc/architecture.md)**: Complete design specification

hooks/hooks.json

@@ -0,0 +1,46 @@
+{
+  "SessionStart": [
+    {
+      "matcher": "",
+      "hooks": [
+        {
+          "type": "command",
+          "command": "src/deepwork/hooks/check_version.sh"
+        }
+      ]
+    }
+  ],
+  "UserPromptSubmit": [
+    {
+      "matcher": "",
+      "hooks": [
+        {
+          "type": "command",
+          "command": ".deepwork/jobs/deepwork_rules/hooks/user_prompt_submit.sh"
+        }
+      ]
+    }
+  ],
+  "Stop": [
+    {
+      "matcher": "",
+      "hooks": [
+        {
+          "type": "command",
+          "command": "python -m deepwork.hooks.rules_check"
+        }
+      ]
+    }
+  ],
+  "SubagentStop": [
+    {
+      "matcher": "",
+      "hooks": [
+        {
+          "type": "command",
+          "command": "python -m deepwork.hooks.rules_check"
+        }
+      ]
+    }
+  ]
+}