From 9840f48ecb50ba1919017b9e857eb4490aad09b5 Mon Sep 17 00:00:00 2001 From: Noah Horton Date: Thu, 9 Apr 2026 19:03:23 -0600 Subject: [PATCH 01/12] feat: add /record and /new_user skills for new user onboarding MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add two new plugin skills for onboarding new DeepWork users: - /record: "watch and learn" approach to creating workflows — users do their work normally, then /deepwork learn turns it into a repeatable job - /new_user: guided onboarding that introduces DeepWork, offers review rule setup for code projects, and offers to record a first workflow Both skills include gh CLI star prompt, browser tool detection, anonymous DeepSchemas, and formal requirements specs (PLUG-REQ-002, PLUG-REQ-003). The /deepwork skill and learn workflow now route to new_job when invoked after /deepwork:record. README install commands consolidated into a single && chain ending with /deepwork:new_user. Co-Authored-By: Claude Opus 4.6 (1M context) --- README.md | 12 +-- plugins/claude/skills/deepwork/SKILL.md | 9 ++ .../skills/new_user/.deepschema.SKILL.md.yml | 49 ++++++++++ plugins/claude/skills/new_user/SKILL.md | 57 +++++++++++ .../skills/record/.deepschema.SKILL.md.yml | 64 +++++++++++++ plugins/claude/skills/record/SKILL.md | 95 +++++++++++++++++++ .../cli_plugins/PLUG-REQ-002-record-skill.md | 46 +++++++++ .../PLUG-REQ-003-new-user-skill.md | 40 ++++++++ .../standard_jobs/deepwork_jobs/job.yml | 15 +++ 9 files changed, 379 insertions(+), 8 deletions(-) create mode 100644 plugins/claude/skills/new_user/.deepschema.SKILL.md.yml create mode 100644 plugins/claude/skills/new_user/SKILL.md create mode 100644 plugins/claude/skills/record/.deepschema.SKILL.md.yml create mode 100644 plugins/claude/skills/record/SKILL.md create mode 100644 specs/deepwork/cli_plugins/PLUG-REQ-002-record-skill.md create mode 100644 specs/deepwork/cli_plugins/PLUG-REQ-003-new-user-skill.md diff --git a/README.md b/README.md index 343c96ca..06e1c3aa 100644 --- a/README.md +++ b/README.md @@ -8,13 +8,10 @@ DeepWork fixes this with two systems: **Workflows** that force agents to follow ### Claude Code (Terminal) ``` -claude plugin marketplace add Unsupervisedcom/deepwork -claude plugin install deepwork@deepwork-plugins - -claude +claude plugin marketplace add Unsupervisedcom/deepwork && claude plugin install deepwork@deepwork-plugins && claude "/deepwork:new_user" ``` -Then start a new session. First, do the task you want to automate — just ask Claude to do it, and work with Claude to refine it as you go: +The onboarding flow will introduce you to DeepWork and help you get started. Or, do the task you want to automate — just ask Claude to do it, and work with Claude to refine it as you go: ``` Research our top 3 competitors and write a SWOT analysis for each one. ``` @@ -137,11 +134,10 @@ Workflows ensure the agent follows the right process. DeepSchemas ensure individ In Claude Code: ``` -claude plugin marketplace add Unsupervisedcom/deepwork -claude plugin install deepwork@deepwork-plugins +claude plugin marketplace add Unsupervisedcom/deepwork && claude plugin install deepwork@deepwork-plugins && claude "/deepwork:new_user" ``` -Start a new Claude Code session after installing. +The onboarding flow walks you through setup. If you prefer to skip it, just start a new Claude Code session. > **Note:** If your folder isn't a Git repo yet, run `git init` first. diff --git a/plugins/claude/skills/deepwork/SKILL.md b/plugins/claude/skills/deepwork/SKILL.md index 31782925..54670846 100644 --- a/plugins/claude/skills/deepwork/SKILL.md +++ b/plugins/claude/skills/deepwork/SKILL.md @@ -71,3 +71,12 @@ When the user invokes `/deepwork`, parse their intent: - **Explicit workflow**: `/deepwork ` → start the `` workflow - **General request**: `/deepwork ` → infer best match from available workflows - **No context**: `/deepwork` alone → ask user to choose from available workflows + +### Special case: `/deepwork learn` after `/deepwork:record` + +If the user invokes `/deepwork learn` and `/deepwork:record` was used earlier in this +conversation, the session captured a new workflow from scratch — there is no existing job +to learn from. Instead of starting the `learn` workflow, start the `new_job` workflow +(`job_name: "deepwork_jobs"`, `workflow_name: "new_job"`) with a goal summarizing the +workflow the user recorded. Use the conversation history as the primary input for defining +the job's steps, inputs, and outputs. diff --git a/plugins/claude/skills/new_user/.deepschema.SKILL.md.yml b/plugins/claude/skills/new_user/.deepschema.SKILL.md.yml new file mode 100644 index 00000000..29f54c58 --- /dev/null +++ b/plugins/claude/skills/new_user/.deepschema.SKILL.md.yml @@ -0,0 +1,49 @@ +requirements: + # PLUG-REQ-003.1.2 + disable-model-invocation: > + The skill MUST set `disable-model-invocation: true` in its frontmatter so + that it is only triggered by explicit user invocation (`/new_user`), not by + the agent autonomously. + + # PLUG-REQ-003.2.1 + gh-star-check: > + The skill MUST check if the `gh` CLI is installed and, if present, use + `AskUserQuestion` to offer to star the DeepWork repo. If `gh` is not + installed, the skill MUST skip this step without mentioning it. + + # PLUG-REQ-003.2.3 + gh-star-command: > + If the user agrees to star the repo, the skill MUST run + `gh api -X PUT /user/starred/Unsupervisedcom/deepwork`. + + # PLUG-REQ-003.3.1 + introduction-content: > + The skill MUST print a concise introduction covering Workflows, Reviews, + and DeepSchemas, and MUST mention that the three systems work together. + + # PLUG-REQ-003.4.1 + code-project-detection: > + The skill MUST check whether the project appears to be a code project + before offering review rule setup. + + # PLUG-REQ-003.4.2 + review-setup-offer: > + For code projects, the skill MUST use `AskUserQuestion` to offer review + rule setup and invoke `/deepwork:configure_reviews` if accepted. + + # PLUG-REQ-003.4.4 + skip-non-code: > + If the project is not a code project, the skill MUST skip the review + setup step entirely. + + # PLUG-REQ-003.5.1 + workflow-recording-offer: > + After review setup completes or is skipped, the skill MUST use + `AskUserQuestion` to explain workflows and offer to start + `/deepwork:record`. + + # PLUG-REQ-003.5.3 + decline-guidance: > + If the user declines workflow recording, the skill MUST inform them they + can run `/deepwork:record` anytime and that `/deepwork` is the main entry + point. diff --git a/plugins/claude/skills/new_user/SKILL.md b/plugins/claude/skills/new_user/SKILL.md new file mode 100644 index 00000000..f320c57d --- /dev/null +++ b/plugins/claude/skills/new_user/SKILL.md @@ -0,0 +1,57 @@ +--- +name: new_user +description: "Welcome new users to DeepWork — introduce features, set up reviews, and optionally record a first workflow" +disable-model-invocation: true +--- + +# New User Onboarding + +Guide a new user through what DeepWork can do and help them get started. + +## Flow + +### 1. GitHub star (optional) + +Check if the `gh` CLI is installed by running `which gh`. + +If `gh` is available, use `AskUserQuestion` to say something like: + +> Thanks for installing DeepWork! Would you mind starring the repo on GitHub so you get notified about updates? + +If they agree, run: + +```bash +gh repo edit Unsupervisedcom/deepwork --visibility public 2>/dev/null; gh api -X PUT /user/starred/Unsupervisedcom/deepwork +``` + +If `gh` is not installed, skip this entirely — do not mention it. + +### 2. Introduce DeepWork + +Print a brief welcome message explaining what DeepWork does. Keep it concise — a few sentences, not a wall of text. Cover the three main capabilities: + +- **Workflows** — structured, multi-step processes with quality gates. Do a task once with Claude, then turn it into a repeatable workflow. Examples: competitive research, tutorial writing, API audits, monthly reporting. +- **Reviews** — automated code review rules that run against every change. Define what to check for in `.deepreview` configs, then run `/review`. Catches regressions, style issues, doc drift, security problems. +- **DeepSchemas** — file-level contracts that validate structure and requirements at write time. Define once, enforce everywhere. + +Mention that these three layers work together: workflows enforce process, schemas enforce file contracts, reviews verify output. + +### 3. Review rules (for code projects) + +Check if this looks like a code project (e.g., has source files, a `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, a `src/` directory, etc.). + +- **If it is a code project**: use `AskUserQuestion` to explain that DeepWork can set up automated review rules for the project — these run every time `/review` is called and catch issues automatically. Ask if they'd like to set up review rules now. + - If yes: invoke the `/deepwork:configure_reviews` skill. + - If no: continue to the next step. +- **If it is NOT a code project** (or you can't tell): skip this step. + +### 4. Offer to record a workflow + +Use `AskUserQuestion` to explain what workflows are in a bit more detail: + +> Workflows let you capture a multi-step process and replay it reliably. You do the task once — research, analysis, report writing, whatever it is — and DeepWork turns it into a structured workflow with quality gates. Next time, the agent follows the exact same process. +> +> Would you like to record a workflow now? You'll just do the task like normal, and when you're done we'll turn it into a reusable workflow. + +If they say yes, invoke the `/deepwork:record` skill. +If they say no, let them know they can run `/deepwork:record` anytime to get started, and that `/deepwork` is the main entry point for all DeepWork features. diff --git a/plugins/claude/skills/record/.deepschema.SKILL.md.yml b/plugins/claude/skills/record/.deepschema.SKILL.md.yml new file mode 100644 index 00000000..7d9edf00 --- /dev/null +++ b/plugins/claude/skills/record/.deepschema.SKILL.md.yml @@ -0,0 +1,64 @@ +requirements: + # PLUG-REQ-002.6.1 + gh-star-check: > + The skill MUST check if the `gh` CLI is installed and, if present, use + `AskUserQuestion` to offer to star the DeepWork repo. If `gh` is not + installed, the skill MUST skip this step without mentioning it. + + # PLUG-REQ-002.6.2 + gh-star-command: > + If the user agrees to star the repo, the skill MUST run + `gh api -X PUT /user/starred/Unsupervisedcom/deepwork`. + + # PLUG-REQ-002.1.1 + workflow-name-prompt: > + The skill MUST ask the user for a workflow name before proceeding. + + # PLUG-REQ-002.2.1 + browser-tool-detection: > + The skill MUST check whether `mcp__claude-in-chrome__*` or + `mcp__plugin_playwright_playwright__*` tools are available before asking + about browser needs. + + # PLUG-REQ-002.2.2 + browser-question-conditional: > + The skill MUST only ask about website access when no browser tools are + detected. If browser tools are already available, the question MUST be + skipped entirely. + + # PLUG-REQ-002.2.3 + chrome-setup-guidance: > + When the user confirms they need website access and no browser tools are + available, the skill MUST tell them to run `/chrome` to set up Claude for + Chrome. + + # PLUG-REQ-002.3.1 + clear-handoff-message: > + The skill MUST display a clear, bold-formatted message telling the user to + proceed with their workflow normally and to run `/deepwork learn` when + done. + + # PLUG-REQ-002.4.1 + clarify-non-obvious-actions: > + During the workflow, the agent MUST ask for reasoning when the user makes + requests that would not be understandable as a repeatable workflow step — + e.g., removing a specific item without explanation, applying an unexplained + filter, or making a domain-specific judgment call. + + # PLUG-REQ-002.4.2 + no-unnecessary-clarification: > + The agent MUST NOT ask for reasoning when the instruction clearly maps to + a repeatable step, the reasoning is obvious from context, or the user has + already explained their reasoning. + + # PLUG-REQ-002.5.1 + catch-done-signal: > + If the user signals completion without running `/deepwork learn`, the agent + MUST use `AskUserQuestion` to confirm whether they want to create a + repeatable DeepWork job, and if so, invoke `/deepwork learn`. + + # PLUG-REQ-002.1.2 + disable-model-invocation: > + The skill MUST set `disable-model-invocation: true` in its frontmatter so + that it is only triggered by explicit user invocation (`/record`), not by + the agent autonomously. diff --git a/plugins/claude/skills/record/SKILL.md b/plugins/claude/skills/record/SKILL.md new file mode 100644 index 00000000..17686403 --- /dev/null +++ b/plugins/claude/skills/record/SKILL.md @@ -0,0 +1,95 @@ +--- +name: record +description: "Record a workflow by doing it — watch and learn approach to creating DeepWork jobs" +disable-model-invocation: true +--- + +# Record a Workflow + +Help the user create a new DeepWork job by watching them do the work naturally, then turning that into a repeatable workflow. + +## Flow + +### 0. GitHub star (optional) + +Check if the `gh` CLI is installed by running `which gh`. + +If `gh` is available, use `AskUserQuestion` to say something like: + +> Thanks for using DeepWork! Would you mind starring the repo on GitHub so you get notified about updates? + +If they agree, run: + +```bash +gh api -X PUT /user/starred/Unsupervisedcom/deepwork +``` + +If `gh` is not installed, skip this entirely — do not mention it. + +### 1. Get the workflow name + +Ask the user: "What would you like to call this workflow? A rough name is fine — we can refine it later." + +Wait for their response before continuing. + +### 2. Check browser access (if needed) + +Check whether any `mcp__claude-in-chrome__*` or `mcp__plugin_playwright_playwright__*` tools are available. + +- **If browser tools ARE available**: skip this step entirely. +- **If browser tools are NOT available**: use `AskUserQuestion` to ask: + + > Will this workflow involve accessing websites (e.g., pulling data from a site, filling out forms, navigating web apps)? + + If they answer yes, tell them: + + > Run **`/chrome`** to set up Claude for Chrome so I can interact with websites during this workflow. + + Wait for them to confirm it's set up before continuing. + +### 3. Hand off to the user + +Output the following message (use bold formatting as shown): + +--- + +Got it — recording workflow: **{workflow_name}** + +**Go ahead and do your workflow using Claude Code like you normally would.** Tell me each step — I'll do the work and keep track of what we do together. + +For example, you can say things like: +- "Go to site X and pull down the latest data on Y" +- "Summarize this into a table" +- "Write a draft report based on these findings" + +**When you're happy with the results, run `/deepwork learn` and I'll turn this session into a repeatable, trustworthy DeepWork workflow.** + +--- + +### 4. During the workflow — clarify non-obvious actions + +As the user gives instructions and you execute them, **watch for requests where the reasoning would not be clear to someone repeating the workflow later**. Context-dependent, one-off, or arbitrary-seeming instructions need clarification. + +**Ask for reasoning when:** +- The user removes, skips, or reorders something without stating why (e.g., "remove item 7 from the list") +- The user applies a filter or threshold that isn't self-evident (e.g., "only keep items over 50") +- The user makes a judgment call that depends on domain knowledge (e.g., "ignore that vendor") + +**Do NOT ask when:** +- The instruction clearly maps to a repeatable workflow step (e.g., "go to site X and pull the latest data on Y") +- The reasoning is obvious from context (e.g., removing duplicates, sorting alphabetically) +- The user already explained their reasoning + +When you do ask, keep it short and focused: + +> "What was the reason for removing item 7? I want to capture the logic so this step works correctly in future runs." + +Incorporate their answer into your understanding of the workflow — don't just note it, use it to inform how you'd generalize the step. + +### 5. Catch the end — prompt for `/deepwork learn` + +If the user signals they're done without running `/deepwork learn` — e.g., "that looks good", "we're done", "that's everything", "ship it" — use `AskUserQuestion` to ask: + +> It looks like the workflow is complete. Would you like me to turn this into a repeatable DeepWork job now? (This will start `/deepwork learn`.) + +If they say yes, invoke the `/deepwork learn` skill. diff --git a/specs/deepwork/cli_plugins/PLUG-REQ-002-record-skill.md b/specs/deepwork/cli_plugins/PLUG-REQ-002-record-skill.md new file mode 100644 index 00000000..d7476e35 --- /dev/null +++ b/specs/deepwork/cli_plugins/PLUG-REQ-002-record-skill.md @@ -0,0 +1,46 @@ +# PLUG-REQ-002: Record Skill (New User Flow) + +## Overview + +The `record` skill provides a "watch and learn" approach to creating DeepWork workflows. Instead of defining a job upfront, users do their work naturally with Claude Code while the skill observes, clarifies non-obvious decisions, and then turns the session into a repeatable DeepWork job via `/deepwork learn`. + +This skill targets new users who know *what* they want to automate but haven't yet learned how to define a DeepWork job from scratch. + +## Requirements + +### PLUG-REQ-002.1: Skill Setup + +1. The plugin MUST provide a `record` skill at `plugins/claude/skills/record/SKILL.md`. +2. The skill MUST set `disable-model-invocation: true` in its YAML frontmatter so it is only triggered by explicit user invocation (`/record`), not autonomously by the agent. +3. The skill's YAML frontmatter `name` field MUST be `"record"`. +4. The skill's YAML frontmatter MUST include a `description` field. + +### PLUG-REQ-002.2: Browser Access Check + +1. The skill MUST check whether browser automation tools (`mcp__claude-in-chrome__*` or `mcp__plugin_playwright_playwright__*`) are available in the current session. +2. If browser tools are already available, the skill MUST skip the browser question entirely. +3. If no browser tools are available, the skill MUST ask the user (via `AskUserQuestion`) whether they expect to need website access during the workflow. +4. If the user confirms they need website access, the skill MUST tell them to run `/chrome` to set up Claude for Chrome and wait for confirmation before proceeding. + +### PLUG-REQ-002.3: Handoff Message + +1. After collecting the workflow name and resolving browser access, the skill MUST display a clear, bold-formatted message that tells the user to proceed with their workflow normally using Claude Code. +2. The handoff message MUST tell the user to run `/deepwork learn` when they are satisfied with the results. + +### PLUG-REQ-002.4: Clarifying Non-Obvious Actions + +1. During the workflow, the agent MUST ask for reasoning when the user makes requests that would not be understandable as a repeatable workflow step — e.g., removing a specific item without explanation, applying an unexplained filter or threshold, or making a domain-specific judgment call. +2. The agent MUST NOT ask for reasoning when the instruction clearly maps to a repeatable step, the reasoning is obvious from context, or the user has already explained their reasoning. +3. When asking for reasoning, the agent SHOULD keep the question short and focused on capturing the logic for future runs. + +### PLUG-REQ-002.5: Completion Detection + +1. If the user signals completion (e.g., "that looks good", "we're done", "ship it") without running `/deepwork learn`, the agent MUST use `AskUserQuestion` to confirm whether they want to create a repeatable DeepWork job. +2. If the user confirms, the agent MUST invoke the `/deepwork learn` skill. + +### PLUG-REQ-002.6: GitHub Star Prompt + +1. As the very first step, the skill MUST check if the `gh` CLI is installed (via `which gh`). +2. If `gh` is available, the skill MUST use `AskUserQuestion` to offer to star the DeepWork repo on GitHub so the user gets update notifications. +3. If the user agrees, the skill MUST run `gh api -X PUT /user/starred/Unsupervisedcom/deepwork`. +4. If `gh` is not installed, the skill MUST skip this step entirely without mentioning it. diff --git a/specs/deepwork/cli_plugins/PLUG-REQ-003-new-user-skill.md b/specs/deepwork/cli_plugins/PLUG-REQ-003-new-user-skill.md new file mode 100644 index 00000000..2ea080af --- /dev/null +++ b/specs/deepwork/cli_plugins/PLUG-REQ-003-new-user-skill.md @@ -0,0 +1,40 @@ +# PLUG-REQ-003: New User Onboarding Skill + +## Overview + +The `new_user` skill provides a guided onboarding experience for users who have just installed DeepWork. It introduces the three main capabilities (Workflows, Reviews, DeepSchemas), optionally sets up review rules for code projects, and offers to record a first workflow. It is user-invocable only — the agent cannot trigger it autonomously. + +## Requirements + +### PLUG-REQ-003.1: Skill Setup + +1. The plugin MUST provide a `new_user` skill at `plugins/claude/skills/new_user/SKILL.md`. +2. The skill MUST set `disable-model-invocation: true` in its YAML frontmatter so it is only triggered by explicit user invocation (`/new_user`), not autonomously by the agent. +3. The skill's YAML frontmatter `name` field MUST be `"new_user"`. +4. The skill's YAML frontmatter MUST include a `description` field. + +### PLUG-REQ-003.2: GitHub Star Prompt + +1. As the very first step, the skill MUST check if the `gh` CLI is installed (via `which gh`). +2. If `gh` is available, the skill MUST use `AskUserQuestion` to thank the user for installing DeepWork and offer to star the repo on GitHub so they get update notifications. +3. If the user agrees, the skill MUST run `gh api -X PUT /user/starred/Unsupervisedcom/deepwork`. +4. If `gh` is not installed, the skill MUST skip this step entirely without mentioning it. + +### PLUG-REQ-003.3: DeepWork Introduction + +1. The skill MUST print a concise introduction explaining what DeepWork does. +2. The introduction MUST cover Workflows (structured multi-step processes with quality gates), Reviews (automated code review rules), and DeepSchemas (file-level contracts with write-time validation). +3. The introduction MUST mention that the three systems work together. + +### PLUG-REQ-003.4: Review Rule Setup (Code Projects) + +1. The skill MUST check whether the project appears to be a code project (e.g., presence of `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `src/` directory, or similar indicators). +2. If it is a code project, the skill MUST use `AskUserQuestion` to explain automated review rules and ask if the user wants to set them up now. +3. If the user agrees, the skill MUST invoke the `/deepwork:configure_reviews` skill. +4. If it is not a code project, the skill MUST skip this step. + +### PLUG-REQ-003.5: Workflow Recording Offer + +1. After the review setup step completes or is skipped, the skill MUST use `AskUserQuestion` to explain what workflows are and ask if the user wants to record one now. +2. If the user agrees, the skill MUST invoke the `/deepwork:record` skill. +3. If the user declines, the skill MUST inform them they can run `/deepwork:record` anytime and that `/deepwork` is the main entry point for all DeepWork features. diff --git a/src/deepwork/standard_jobs/deepwork_jobs/job.yml b/src/deepwork/standard_jobs/deepwork_jobs/job.yml index a35928e0..df78badd 100644 --- a/src/deepwork/standard_jobs/deepwork_jobs/job.yml +++ b/src/deepwork/standard_jobs/deepwork_jobs/job.yml @@ -1704,6 +1704,21 @@ workflows: Think deeply about this task. Reflect on the current conversation to identify learnings from DeepWork job executions, improve job instructions with generalizable insights, and capture bespoke (run-specific) learnings in AGENTS.md files in the deepest common folder that would contain all work on the topic in the future. + ## Pre-check: Recording Session + + Before proceeding, check whether `/deepwork:record` was invoked earlier in this conversation. + If it was, this session captured a new workflow from scratch — there is no existing job + to learn from. Instead, start the `new_job` workflow to turn the recorded session into + a repeatable DeepWork job: + + 1. Call `start_workflow` with `job_name: "deepwork_jobs"`, `workflow_name: "new_job"`, + and a `goal` summarizing the workflow the user recorded. + 2. Follow the `new_job` workflow steps — use the conversation history as the primary + input for defining the job's steps, inputs, and outputs. + 3. **Do not continue** with the learn steps below. + + If `/deepwork:record` was NOT used, continue with the normal learn flow. + ## Task Analyze the conversation history to extract learnings and improvements, then apply them appropriately: From e3628eedce0f410cc92d59eb6fd28f82b1948796 Mon Sep 17 00:00:00 2001 From: Noah Horton Date: Thu, 9 Apr 2026 19:24:32 -0600 Subject: [PATCH 02/12] fix: address review findings from first review pass - Remove unnecessary `gh repo edit` command from new_user skill - Add new_user/ and record/ to skill directory listings in CLAUDE.md and doc/architecture.md - Fix incorrect requirement ID mapping in record DeepSchema (workflow-name-prompt was mistagged as PLUG-REQ-002.1.1) - Add PLUG-REQ-002.7 requirement for learn-after-record redirect - Update CHANGELOG.md with unreleased changes Co-Authored-By: Claude Opus 4.6 (1M context) --- CHANGELOG.md | 8 ++++++++ doc/architecture.md | 2 ++ plugins/claude/skills/new_user/SKILL.md | 2 +- plugins/claude/skills/record/.deepschema.SKILL.md.yml | 2 +- specs/deepwork/cli_plugins/PLUG-REQ-002-record-skill.md | 6 ++++++ 5 files changed, 18 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0d9dff6f..cddf335c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,8 +9,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added +- `/record` skill: "watch and learn" approach to creating DeepWork workflows — users do their work normally, then `/deepwork learn` turns it into a repeatable job +- `/new_user` skill: guided onboarding that introduces DeepWork, offers review rule setup for code projects, and offers to record a first workflow +- `/deepwork learn` now routes to the `new_job` workflow when invoked after `/deepwork:record` +- Requirements specs PLUG-REQ-002 (record skill) and PLUG-REQ-003 (new user skill) +- Anonymous DeepSchemas for both new skills + ### Changed +- README install commands consolidated into a single `&&`-joined command ending with `/deepwork:new_user` + ### Fixed ### Removed diff --git a/doc/architecture.md b/doc/architecture.md index 8b7ac6b8..89802f85 100644 --- a/doc/architecture.md +++ b/doc/architecture.md @@ -113,6 +113,8 @@ deepwork/ # DeepWork tool repository │ │ │ ├── deepreviews/SKILL.md │ │ │ ├── deepwork/SKILL.md │ │ │ ├── deepschema/SKILL.md +│ │ │ ├── new_user/SKILL.md +│ │ │ ├── record/SKILL.md │ │ │ └── review/SKILL.md │ │ ├── hooks/ # hooks.json, post_commit_reminder.sh, post_compact.sh, startup_context.sh, deepschema_write.sh │ │ └── .mcp.json # MCP server config diff --git a/plugins/claude/skills/new_user/SKILL.md b/plugins/claude/skills/new_user/SKILL.md index f320c57d..9ac24981 100644 --- a/plugins/claude/skills/new_user/SKILL.md +++ b/plugins/claude/skills/new_user/SKILL.md @@ -21,7 +21,7 @@ If `gh` is available, use `AskUserQuestion` to say something like: If they agree, run: ```bash -gh repo edit Unsupervisedcom/deepwork --visibility public 2>/dev/null; gh api -X PUT /user/starred/Unsupervisedcom/deepwork +gh api -X PUT /user/starred/Unsupervisedcom/deepwork ``` If `gh` is not installed, skip this entirely — do not mention it. diff --git a/plugins/claude/skills/record/.deepschema.SKILL.md.yml b/plugins/claude/skills/record/.deepschema.SKILL.md.yml index 7d9edf00..35e80c50 100644 --- a/plugins/claude/skills/record/.deepschema.SKILL.md.yml +++ b/plugins/claude/skills/record/.deepschema.SKILL.md.yml @@ -10,7 +10,7 @@ requirements: If the user agrees to star the repo, the skill MUST run `gh api -X PUT /user/starred/Unsupervisedcom/deepwork`. - # PLUG-REQ-002.1.1 + # PLUG-REQ-002.3.1 (workflow name collection is part of the handoff flow) workflow-name-prompt: > The skill MUST ask the user for a workflow name before proceeding. diff --git a/specs/deepwork/cli_plugins/PLUG-REQ-002-record-skill.md b/specs/deepwork/cli_plugins/PLUG-REQ-002-record-skill.md index d7476e35..3924c847 100644 --- a/specs/deepwork/cli_plugins/PLUG-REQ-002-record-skill.md +++ b/specs/deepwork/cli_plugins/PLUG-REQ-002-record-skill.md @@ -44,3 +44,9 @@ This skill targets new users who know *what* they want to automate but haven't y 2. If `gh` is available, the skill MUST use `AskUserQuestion` to offer to star the DeepWork repo on GitHub so the user gets update notifications. 3. If the user agrees, the skill MUST run `gh api -X PUT /user/starred/Unsupervisedcom/deepwork`. 4. If `gh` is not installed, the skill MUST skip this step entirely without mentioning it. + +### PLUG-REQ-002.7: Learn After Record Redirect + +1. When `/deepwork learn` is invoked in a conversation where `/deepwork:record` was used, the `/deepwork` skill MUST start the `new_job` workflow (`job_name: "deepwork_jobs"`, `workflow_name: "new_job"`) instead of the `learn` workflow. +2. The `learn` step in the `deepwork_jobs` standard job MUST check for a prior `/deepwork:record` invocation and redirect to `new_job` if found. +3. The conversation history from the recording session MUST be used as the primary input for defining the new job's steps, inputs, and outputs. From de8f91e8d3c02e00ebd12fcdaebda82574e65973 Mon Sep 17 00:00:00 2001 From: Noah Horton Date: Thu, 9 Apr 2026 19:28:27 -0600 Subject: [PATCH 03/12] fix: address pass 2 review findings - Update install instructions in CLAUDE.md and architecture.md to match README's single-line format - Add new_user and record to CLAUDE.md skill list - Fix mislabeled workflow-name-prompt requirement ID in record DeepSchema - Add PLUG-REQ-002.7.2 validation to job.yml DeepSchema (learn-record redirect) - Add PLUG-REQ-002.7.1 validation via new deepwork SKILL.md DeepSchema - Add PLUG-REQ-003.5.2 coverage to new_user DeepSchema - Expand claude_plugin_skill_instructions .deepreview rule with record and new_user skill verification sections Co-Authored-By: Claude Opus 4.6 (1M context) --- doc/architecture.md | 3 +- plugins/claude/.deepreview | 30 +++++++++++++++++++ .../skills/deepwork/.deepschema.SKILL.md.yml | 6 ++++ .../skills/new_user/.deepschema.SKILL.md.yml | 3 +- .../skills/record/.deepschema.SKILL.md.yml | 3 +- .../deepwork_jobs/.deepschema.job.yml.yml | 7 +++++ 6 files changed, 48 insertions(+), 4 deletions(-) create mode 100644 plugins/claude/skills/deepwork/.deepschema.SKILL.md.yml diff --git a/doc/architecture.md b/doc/architecture.md index 89802f85..fd24382d 100644 --- a/doc/architecture.md +++ b/doc/architecture.md @@ -385,8 +385,7 @@ This section describes how AI agents (like Claude Code) actually execute jobs us 1. **Install Plugin** (one-time): ``` # In Claude Code - claude plugin marketplace add Unsupervisedcom/deepwork - claude plugin install deepwork@deepwork-plugins + claude plugin marketplace add Unsupervisedcom/deepwork && claude plugin install deepwork@deepwork-plugins && claude "/deepwork:new_user" ``` 2. **Define a Job** (once per job type): diff --git a/plugins/claude/.deepreview b/plugins/claude/.deepreview index b02b719b..9519678a 100644 --- a/plugins/claude/.deepreview +++ b/plugins/claude/.deepreview @@ -59,6 +59,36 @@ claude_plugin_skill_instructions: - **PLUG-REQ-001.13.4**: The skill must describe workflow quality gates and how `finished_step` triggers reviews on step outputs. + ## record skill (plugins/claude/skills/record/SKILL.md) + + - **PLUG-REQ-002.2**: The skill must check for browser tools and + only ask about website access when none are detected. + - **PLUG-REQ-002.3**: After collecting the workflow name and + resolving browser access, the skill must display a clear handoff + message telling the user to proceed normally and run + `/deepwork learn` when done. + - **PLUG-REQ-002.4**: During the workflow, the skill must clarify + non-obvious actions (unexplained removals, filters, judgment + calls) but not ask about clearly repeatable steps. + - **PLUG-REQ-002.5**: The skill must detect completion signals and + offer to invoke `/deepwork learn`. + - **PLUG-REQ-002.6**: The skill must check for `gh` CLI and offer + a GitHub star prompt as the first step; skip silently if `gh` + is not installed. + + ## new_user skill (plugins/claude/skills/new_user/SKILL.md) + + - **PLUG-REQ-003.2**: The skill must check for `gh` CLI and offer + a GitHub star prompt as the first step; skip silently if `gh` + is not installed. + - **PLUG-REQ-003.3**: The skill must print a concise introduction + covering Workflows, Reviews, and DeepSchemas, and mention that + the three systems work together. + - **PLUG-REQ-003.4**: The skill must detect code projects and + offer review rule setup via `/deepwork:configure_reviews`. + - **PLUG-REQ-003.5**: The skill must offer to record a workflow + via `/deepwork:record` and provide guidance if declined. + Output Format: - PASS: All behavioral requirements are adequately conveyed. - FAIL: List each requirement ID that is not adequately covered, diff --git a/plugins/claude/skills/deepwork/.deepschema.SKILL.md.yml b/plugins/claude/skills/deepwork/.deepschema.SKILL.md.yml new file mode 100644 index 00000000..e87e5918 --- /dev/null +++ b/plugins/claude/skills/deepwork/.deepschema.SKILL.md.yml @@ -0,0 +1,6 @@ +requirements: + # PLUG-REQ-002.7.1 + learn-record-redirect: > + The skill MUST include a special case for `/deepwork learn` after + `/deepwork:record`: when `/deepwork:record` was used in the conversation, + the skill MUST start the `new_job` workflow instead of the `learn` workflow. diff --git a/plugins/claude/skills/new_user/.deepschema.SKILL.md.yml b/plugins/claude/skills/new_user/.deepschema.SKILL.md.yml index 29f54c58..605d49a0 100644 --- a/plugins/claude/skills/new_user/.deepschema.SKILL.md.yml +++ b/plugins/claude/skills/new_user/.deepschema.SKILL.md.yml @@ -36,10 +36,11 @@ requirements: If the project is not a code project, the skill MUST skip the review setup step entirely. - # PLUG-REQ-003.5.1 + # PLUG-REQ-003.5.1, PLUG-REQ-003.5.2 workflow-recording-offer: > After review setup completes or is skipped, the skill MUST use `AskUserQuestion` to explain workflows and offer to start + `/deepwork:record`. If the user agrees, the skill MUST invoke `/deepwork:record`. # PLUG-REQ-003.5.3 diff --git a/plugins/claude/skills/record/.deepschema.SKILL.md.yml b/plugins/claude/skills/record/.deepschema.SKILL.md.yml index 35e80c50..63acf782 100644 --- a/plugins/claude/skills/record/.deepschema.SKILL.md.yml +++ b/plugins/claude/skills/record/.deepschema.SKILL.md.yml @@ -10,7 +10,8 @@ requirements: If the user agrees to star the repo, the skill MUST run `gh api -X PUT /user/starred/Unsupervisedcom/deepwork`. - # PLUG-REQ-002.3.1 (workflow name collection is part of the handoff flow) + # Behavioral requirement — not a numbered sub-requirement in the spec; + # part of the record skill's setup flow prior to PLUG-REQ-002.3 handoff. workflow-name-prompt: > The skill MUST ask the user for a workflow name before proceeding. diff --git a/src/deepwork/standard_jobs/deepwork_jobs/.deepschema.job.yml.yml b/src/deepwork/standard_jobs/deepwork_jobs/.deepschema.job.yml.yml index 7433bf4b..9c1df859 100644 --- a/src/deepwork/standard_jobs/deepwork_jobs/.deepschema.job.yml.yml +++ b/src/deepwork/standard_jobs/deepwork_jobs/.deepschema.job.yml.yml @@ -21,3 +21,10 @@ requirements: The learn workflow's quality review MUST enforce "Generalizable Learnings Applied", "Bespoke Learnings Captured", and "Prevention Opportunities Evaluated" as process requirements. + + # PLUG-REQ-002.7.2 + learn-record-redirect: > + The learn step instructions MUST include a pre-check for whether + `/deepwork:record` was used in the conversation, and if so, MUST + redirect to the `new_job` workflow instead of continuing with the + normal learn flow. From d3822075a2aafbd6f4f0039d2ef20a4538f8723b Mon Sep 17 00:00:00 2001 From: Noah Horton Date: Thu, 9 Apr 2026 19:39:07 -0600 Subject: [PATCH 04/12] feat: include governed target file in DeepSchema compliance reviews DeepSchema compliance reviews for anonymous schemas now inline the governed target file as a reference so reviewers can validate requirements against actual file content without a separate lookup. Also renames the "Reference Materials" section header to "Relevant File Contents" across code, tests, specs, and docs for clarity. - Add DW-REQ-011.11.7: anonymous schemas include governed file as ref - Implement in review_bridge.py::_collect_reference_files() - Rename header in instructions.py and update REVIEW-REQ-005.8 - Update tests, deepreviews SKILL.md, README_REVIEWS.md - Add missing DeepSchema entries for PLUG-REQ-002.7 and PLUG-REQ-003.5.2 Co-Authored-By: Claude Opus 4.6 (1M context) --- README_REVIEWS.md | 2 +- plugins/claude/skills/deepreviews/SKILL.md | 2 +- specs/deepwork/DW-REQ-011-deepschema.md | 1 + .../REVIEW-REQ-005-instruction-generation.md | 6 +++--- src/deepwork/deepschema/review_bridge.py | 15 +++++++++++++++ src/deepwork/review/instructions.py | 4 ++-- tests/unit/review/test_instructions.py | 6 +++--- 7 files changed, 26 insertions(+), 10 deletions(-) diff --git a/README_REVIEWS.md b/README_REVIEWS.md index 0679575e..359fd1b1 100644 --- a/README_REVIEWS.md +++ b/README_REVIEWS.md @@ -107,7 +107,7 @@ rule_name: all_changed_filenames: true unchanged_matching_files: true reference_files: # Optional. Files whose contents are inlined - - path: "docs/style_guide.md" # into a "## Reference Materials" section of + - path: "docs/style_guide.md" # into a "## Relevant File Contents" section of description: "Style guide" # every generated review instruction file. ``` diff --git a/plugins/claude/skills/deepreviews/SKILL.md b/plugins/claude/skills/deepreviews/SKILL.md index 43d88236..834845a7 100644 --- a/plugins/claude/skills/deepreviews/SKILL.md +++ b/plugins/claude/skills/deepreviews/SKILL.md @@ -59,7 +59,7 @@ rule_name: ### Reference Files -`reference_files` inline small support files (style guides, schemas, templates) into a `## Reference Materials` section of every generated review instruction file. Paths are resolved relative to the `.deepreview` file's directory. Inlining is capped at 20 files and 256 KB of total content per review — entries beyond the caps are listed in an omitted-summary line; oversized files are truncated. Missing files produce a graceful marker rather than aborting the review. Use this instead of asking the reviewer to Read each file at runtime. +`reference_files` inline small support files (style guides, schemas, templates) into a `## Relevant File Contents` section of every generated review instruction file. Paths are resolved relative to the `.deepreview` file's directory. Inlining is capped at 20 files and 256 KB of total content per review — entries beyond the caps are listed in an omitted-summary line; oversized files are truncated. Missing files produce a graceful marker rather than aborting the review. Use this instead of asking the reviewer to Read each file at runtime. ## Review Strategies diff --git a/specs/deepwork/DW-REQ-011-deepschema.md b/specs/deepwork/DW-REQ-011-deepschema.md index 170d7c59..fec203e9 100644 --- a/specs/deepwork/DW-REQ-011-deepschema.md +++ b/specs/deepwork/DW-REQ-011-deepschema.md @@ -86,3 +86,4 @@ The DeepSchema system provides rich, file-level schemas with automatic validatio 4. The order of inlined reference files MUST be deterministic across runs for a given schema. 5. When a referenced file cannot be located on disk, the bridge MUST skip it and surface an error through the `errors` return of `generate_review_rules`. A missing reference file MUST NOT prevent the rule from being generated. 6. Reference entries whose `path` begins with `http://` or `https://` MUST be skipped without producing an error, since they are informational pointers rather than local files. +7. For anonymous schemas, the bridge MUST include the governed target file (the sibling file derived from the schema filename) as a reference file so the reviewer has its contents available without a separate lookup. diff --git a/specs/deepwork/review/REVIEW-REQ-005-instruction-generation.md b/specs/deepwork/review/REVIEW-REQ-005-instruction-generation.md index 3e816e63..96e65b56 100644 --- a/specs/deepwork/review/REVIEW-REQ-005-instruction-generation.md +++ b/specs/deepwork/review/REVIEW-REQ-005-instruction-generation.md @@ -56,10 +56,10 @@ For each `ReviewTask`, the system generates a self-contained markdown instructio 3. The section MUST contain the verbatim stdout of the precomputed command. 4. When the command failed, the section MUST contain an error message with stderr and exit code. -### REVIEW-REQ-005.8: Reference Materials Section +### REVIEW-REQ-005.8: Relevant File Contents Section -1. When a task's `reference_files` is empty, the instruction file MUST NOT contain a "Reference Materials" section. -2. When a task has `reference_files`, the instruction file MUST contain a "## Reference Materials" section placed between "Review Instructions" and "Files to Review". +1. When a task's `reference_files` is empty, the instruction file MUST NOT contain a "Relevant File Contents" section. +2. When a task has `reference_files`, the instruction file MUST contain a "## Relevant File Contents" section placed between "Review Instructions" and "Files to Review". 3. Each inlined file MUST be rendered with a `### {relative_label}` subheading, the optional description, and the file contents inside a fenced code block whose language is inferred from the file extension. 4. The number of inlined reference files MUST NOT exceed `MAX_INLINE_FILES` (20). Entries beyond that cap MUST be listed in an "omitted due to size/count caps" summary line rather than inlined. 5. The total inlined byte size of reference file contents MUST NOT exceed `MAX_INLINE_TOTAL_BYTES` (256 * 1024). Files whose contents would exceed the remaining byte budget MUST be truncated with a visible truncation marker, and any subsequent entries MUST be reported in the omitted summary line. diff --git a/src/deepwork/deepschema/review_bridge.py b/src/deepwork/deepschema/review_bridge.py index 40f9e4a7..839ad512 100644 --- a/src/deepwork/deepschema/review_bridge.py +++ b/src/deepwork/deepschema/review_bridge.py @@ -189,6 +189,21 @@ def _add(raw_path: str, description: str | None, source_field: str) -> None: ) ) + # For anonymous schemas, include the governed target file so the + # reviewer can validate requirements against the actual file content + # without needing a separate lookup. (DW-REQ-011.11.7) + if schema.schema_type == "anonymous": + target_name = anonymous_target_filename(schema.source_path.name) + target_path = (schema_dir / target_name).resolve() + if target_path.exists(): + refs.append( + ReferenceFile( + path=target_path, + relative_label=target_name, + description=f"Target file governed by this schema", + ) + ) + # Note: schema.examples are intentionally NOT inlined — they are listed # in the instructions via _build_examples_section so reviewers know they # exist without bloating the prompt. diff --git a/src/deepwork/review/instructions.py b/src/deepwork/review/instructions.py index 2aa1f963..a407f991 100644 --- a/src/deepwork/review/instructions.py +++ b/src/deepwork/review/instructions.py @@ -246,9 +246,9 @@ def build_instruction_file( parts.append(task.instructions.strip()) parts.append("") - # Reference materials — inlined file contents (subject to caps) + # Relevant file contents — inlined for reviewer context (subject to caps) if task.reference_files: - parts.append("## Reference Materials\n") + parts.append("## Relevant File Contents\n") parts.append(_build_reference_files_section(task.reference_files)) parts.append("") diff --git a/tests/unit/review/test_instructions.py b/tests/unit/review/test_instructions.py index bcba6ee9..9a6a0c10 100644 --- a/tests/unit/review/test_instructions.py +++ b/tests/unit/review/test_instructions.py @@ -613,7 +613,7 @@ def _task_with_refs(self, refs: list[ReferenceFile]) -> ReviewTask: def test_empty_reference_files_no_section(self) -> None: task = _make_task() content = build_instruction_file(task) - assert "## Reference Materials" not in content + assert "## Relevant File Contents" not in content # THIS TEST VALIDATES A HARD REQUIREMENT (REVIEW-REQ-005.8.2, REVIEW-REQ-005.8.3). # YOU MUST NOT MODIFY THIS TEST UNLESS THE REQUIREMENT CHANGES @@ -624,7 +624,7 @@ def test_inlines_content_with_description(self, tmp_path: Path) -> None: [ReferenceFile(path=f, relative_label="example.yml", description="Sample YAML")] ) content = build_instruction_file(task) - assert "## Reference Materials" in content + assert "## Relevant File Contents" in content assert "### example.yml" in content assert "Sample YAML" in content assert "```yaml" in content @@ -669,4 +669,4 @@ def test_missing_file_graceful(self, tmp_path: Path) -> None: content = build_instruction_file(task) assert "could not inline nope.txt" in content # Section still rendered; other content not aborted. - assert "## Reference Materials" in content + assert "## Relevant File Contents" in content From 4022c6d082388d1fcbf8982c346c21aa62cd9d62 Mon Sep 17 00:00:00 2001 From: Noah Horton Date: Thu, 9 Apr 2026 19:40:25 -0600 Subject: [PATCH 05/12] docs: clarify that @filepath refs in review instructions are not expanded MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The reviewing agent must Read these files itself — they are path pointers, not auto-expanded content. Any content the reviewer needs without a round-trip should go in reference_files instead. Co-Authored-By: Claude Opus 4.6 (1M context) --- src/deepwork/review/instructions.py | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/src/deepwork/review/instructions.py b/src/deepwork/review/instructions.py index a407f991..58525aa5 100644 --- a/src/deepwork/review/instructions.py +++ b/src/deepwork/review/instructions.py @@ -252,7 +252,12 @@ def build_instruction_file( parts.append(_build_reference_files_section(task.reference_files)) parts.append("") - # Files to review (omitted for inline-content tasks with no files) + # Files to review (omitted for inline-content tasks with no files). + # NOTE: The @filepath references below are NOT auto-expanded when the + # instruction file is consumed by the reviewing agent. They are path + # pointers — the agent must Read each file itself. Any content that + # the reviewer needs without a round-trip should go in reference_files + # (rendered in "Relevant File Contents" above). if task.files_to_review: parts.append("## Files to Review\n") for filepath in task.files_to_review: From e6696f43f6c6ae4632399040b2d68aca990e2b2b Mon Sep 17 00:00:00 2001 From: Noah Horton Date: Thu, 9 Apr 2026 19:43:03 -0600 Subject: [PATCH 06/12] feat: inline file under review for individual-strategy reviews MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit For individual-strategy reviews, the matched file is now included as a ReferenceFile so its content appears in "Relevant File Contents". The @filepath references in "Files to Review" are not auto-expanded by the reviewing agent, so this ensures reviewers have the file content without a separate Read call. Adds REVIEW-REQ-004.3.5. The review_bridge.py change for anonymous schemas remains — it serves a different purpose: inlining the governed *target* file (e.g., SKILL.md), not the schema file being reviewed (.deepschema.SKILL.md.yml). Co-Authored-By: Claude Opus 4.6 (1M context) --- .../REVIEW-REQ-004-rule-matching-and-strategies.md | 1 + src/deepwork/review/matcher.py | 13 +++++++++++-- 2 files changed, 12 insertions(+), 2 deletions(-) diff --git a/specs/deepwork/review/REVIEW-REQ-004-rule-matching-and-strategies.md b/specs/deepwork/review/REVIEW-REQ-004-rule-matching-and-strategies.md index 0eb42e7d..545c9e55 100644 --- a/specs/deepwork/review/REVIEW-REQ-004-rule-matching-and-strategies.md +++ b/specs/deepwork/review/REVIEW-REQ-004-rule-matching-and-strategies.md @@ -29,6 +29,7 @@ After discovering review rules (REVIEW-REQ-002) and changed files (REVIEW-REQ-00 2. Each task's `files_to_review` MUST contain exactly one file path. 3. The task's `rule_name` MUST be the rule name. 4. The task's `instructions` MUST be the rule's resolved instruction text. +5. The matched file MUST be included as a `ReferenceFile` in the task's `reference_files` so its content is inlined in the "Relevant File Contents" section. This is necessary because `@filepath` references in "Files to Review" are not auto-expanded by the reviewing agent. ### REVIEW-REQ-004.4: Strategy — matches_together diff --git a/src/deepwork/review/matcher.py b/src/deepwork/review/matcher.py index 55bddb14..5832e79d 100644 --- a/src/deepwork/review/matcher.py +++ b/src/deepwork/review/matcher.py @@ -9,7 +9,7 @@ import subprocess from pathlib import Path -from deepwork.review.config import ReviewRule, ReviewTask +from deepwork.review.config import ReferenceFile, ReviewRule, ReviewTask class GitDiffError(Exception): @@ -227,6 +227,15 @@ def match_files_to_rules( if rule.strategy == "individual": for filepath in matched: + # Include the file under review as a reference so its + # content is inlined in "Relevant File Contents" — the + # @filepath in "Files to Review" is NOT auto-expanded. + file_ref = ReferenceFile( + path=(project_root / filepath).resolve(), + relative_label=filepath, + description="File under review", + ) + task_refs = [file_ref] + list(rule.reference_files) tasks.append( ReviewTask( rule_name=rule.name, @@ -236,7 +245,7 @@ def match_files_to_rules( source_location=source_location, all_changed_filenames=all_filenames, precomputed_info_bash_command=precompute_cmd, - reference_files=rule.reference_files, + reference_files=task_refs, ) ) From 20aa3ab81181583dc65ba84f8777402a286f5cf8 Mon Sep 17 00:00:00 2001 From: Noah Horton Date: Thu, 9 Apr 2026 19:46:02 -0600 Subject: [PATCH 07/12] fix: remove redundant anonymous schema ref from review_bridge The matcher now inlines the file under review for all individual-strategy reviews (REVIEW-REQ-004.3.5), which covers anonymous schema governed files generically. The bridge-level addition was redundant and would have caused the governed file to appear twice in "Relevant File Contents". DW-REQ-011.11.7 marked as removed, superseded by REVIEW-REQ-004.3.5. Co-Authored-By: Claude Opus 4.6 (1M context) --- specs/deepwork/DW-REQ-011-deepschema.md | 2 +- src/deepwork/deepschema/review_bridge.py | 18 ++++-------------- 2 files changed, 5 insertions(+), 15 deletions(-) diff --git a/specs/deepwork/DW-REQ-011-deepschema.md b/specs/deepwork/DW-REQ-011-deepschema.md index fec203e9..9eb0c421 100644 --- a/specs/deepwork/DW-REQ-011-deepschema.md +++ b/specs/deepwork/DW-REQ-011-deepschema.md @@ -86,4 +86,4 @@ The DeepSchema system provides rich, file-level schemas with automatic validatio 4. The order of inlined reference files MUST be deterministic across runs for a given schema. 5. When a referenced file cannot be located on disk, the bridge MUST skip it and surface an error through the `errors` return of `generate_review_rules`. A missing reference file MUST NOT prevent the rule from being generated. 6. Reference entries whose `path` begins with `http://` or `https://` MUST be skipped without producing an error, since they are informational pointers rather than local files. -7. For anonymous schemas, the bridge MUST include the governed target file (the sibling file derived from the schema filename) as a reference file so the reviewer has its contents available without a separate lookup. +7. (OPTIONAL — REQUIREMENT REMOVED, superseded by REVIEW-REQ-004.3.5.) diff --git a/src/deepwork/deepschema/review_bridge.py b/src/deepwork/deepschema/review_bridge.py index 839ad512..da3610a8 100644 --- a/src/deepwork/deepschema/review_bridge.py +++ b/src/deepwork/deepschema/review_bridge.py @@ -189,20 +189,10 @@ def _add(raw_path: str, description: str | None, source_field: str) -> None: ) ) - # For anonymous schemas, include the governed target file so the - # reviewer can validate requirements against the actual file content - # without needing a separate lookup. (DW-REQ-011.11.7) - if schema.schema_type == "anonymous": - target_name = anonymous_target_filename(schema.source_path.name) - target_path = (schema_dir / target_name).resolve() - if target_path.exists(): - refs.append( - ReferenceFile( - path=target_path, - relative_label=target_name, - description=f"Target file governed by this schema", - ) - ) + # Note: The governed target file for anonymous schemas is NOT added + # here — the matcher inlines the file under review as a ReferenceFile + # for all individual-strategy reviews (REVIEW-REQ-004.3.5), which + # covers the same case without duplication. # Note: schema.examples are intentionally NOT inlined — they are listed # in the instructions via _build_examples_section so reviewers know they From 302d20945249cb30585d7ecd16ad2be8955ea0e0 Mon Sep 17 00:00:00 2001 From: Noah Horton Date: Thu, 9 Apr 2026 19:46:32 -0600 Subject: [PATCH 08/12] chore: remove unused DW-REQ-011.11.7 (never merged to main) Co-Authored-By: Claude Opus 4.6 (1M context) --- specs/deepwork/DW-REQ-011-deepschema.md | 1 - 1 file changed, 1 deletion(-) diff --git a/specs/deepwork/DW-REQ-011-deepschema.md b/specs/deepwork/DW-REQ-011-deepschema.md index 9eb0c421..170d7c59 100644 --- a/specs/deepwork/DW-REQ-011-deepschema.md +++ b/specs/deepwork/DW-REQ-011-deepschema.md @@ -86,4 +86,3 @@ The DeepSchema system provides rich, file-level schemas with automatic validatio 4. The order of inlined reference files MUST be deterministic across runs for a given schema. 5. When a referenced file cannot be located on disk, the bridge MUST skip it and surface an error through the `errors` return of `generate_review_rules`. A missing reference file MUST NOT prevent the rule from being generated. 6. Reference entries whose `path` begins with `http://` or `https://` MUST be skipped without producing an error, since they are informational pointers rather than local files. -7. (OPTIONAL — REQUIREMENT REMOVED, superseded by REVIEW-REQ-004.3.5.) From fb583aaeca8f9bdd56de421b1897f30c382e88a0 Mon Sep 17 00:00:00 2001 From: Noah Horton Date: Thu, 9 Apr 2026 19:49:24 -0600 Subject: [PATCH 09/12] Apply suggestion from @nhorton --- doc/architecture.md | 1 - 1 file changed, 1 deletion(-) diff --git a/doc/architecture.md b/doc/architecture.md index fd24382d..4ec73319 100644 --- a/doc/architecture.md +++ b/doc/architecture.md @@ -384,7 +384,6 @@ This section describes how AI agents (like Claude Code) actually execute jobs us 1. **Install Plugin** (one-time): ``` - # In Claude Code claude plugin marketplace add Unsupervisedcom/deepwork && claude plugin install deepwork@deepwork-plugins && claude "/deepwork:new_user" ``` From 410d70e1d10896bd083ed9ca7d204a2ec6815641 Mon Sep 17 00:00:00 2001 From: Noah Horton Date: Thu, 9 Apr 2026 19:54:35 -0600 Subject: [PATCH 10/12] test: add REVIEW-REQ-004.3.5 test for individual strategy file inlining Validates that individual-strategy reviews include the matched file as a ReferenceFile in the task's reference_files, ensuring its content is inlined in "Relevant File Contents" for the reviewing agent. Co-Authored-By: Claude Opus 4.6 (1M context) --- tests/unit/review/test_matcher.py | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/tests/unit/review/test_matcher.py b/tests/unit/review/test_matcher.py index cf2846b1..94c2f5a5 100644 --- a/tests/unit/review/test_matcher.py +++ b/tests/unit/review/test_matcher.py @@ -179,6 +179,23 @@ def test_individual_strategy_creates_one_task_per_file(self, tmp_path: Path) -> assert tasks[0].files_to_review == ["app.py"] assert tasks[1].files_to_review == ["lib.py"] + # THIS TEST VALIDATES A HARD REQUIREMENT (REVIEW-REQ-004.3.5). + # YOU MUST NOT MODIFY THIS TEST UNLESS THE REQUIREMENT CHANGES + def test_individual_strategy_inlines_file_as_reference(self, tmp_path: Path) -> None: + """REVIEW-REQ-004.3.5: matched file is included as a ReferenceFile.""" + (tmp_path / "app.py").write_text("pass\n") + rule = _make_rule(strategy="individual", source_dir=tmp_path) + tasks = match_files_to_rules( + ["app.py"], + [rule], + tmp_path, + ) + assert len(tasks) == 1 + ref_labels = [r.relative_label for r in tasks[0].reference_files] + assert "app.py" in ref_labels, ( + "Individual strategy must include the matched file as a ReferenceFile" + ) + # THIS TEST VALIDATES A HARD REQUIREMENT (REVIEW-REQ-004.4.1, REVIEW-REQ-004.4.2). # YOU MUST NOT MODIFY THIS TEST UNLESS THE REQUIREMENT CHANGES def test_matches_together_strategy_creates_single_task(self, tmp_path: Path) -> None: From 19cadbd2802d058294eac8d8d56c851fab9d6319 Mon Sep 17 00:00:00 2001 From: Noah Horton Date: Thu, 9 Apr 2026 19:56:01 -0600 Subject: [PATCH 11/12] docs: emphasize reliability in new_user onboarding introduction Co-Authored-By: Claude Opus 4.6 (1M context) --- plugins/claude/skills/new_user/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/claude/skills/new_user/SKILL.md b/plugins/claude/skills/new_user/SKILL.md index 9ac24981..33247426 100644 --- a/plugins/claude/skills/new_user/SKILL.md +++ b/plugins/claude/skills/new_user/SKILL.md @@ -28,7 +28,7 @@ If `gh` is not installed, skip this entirely — do not mention it. ### 2. Introduce DeepWork -Print a brief welcome message explaining what DeepWork does. Keep it concise — a few sentences, not a wall of text. Cover the three main capabilities: +Print a brief welcome message explaining what DeepWork does. Lead with the core value proposition: DeepWork makes AI agents **reliable**. It gives you mechanisms to be assured that Claude will do the right things in the process of achieving your requests. Keep it concise — a few sentences, not a wall of text. Then cover the three main capabilities: - **Workflows** — structured, multi-step processes with quality gates. Do a task once with Claude, then turn it into a repeatable workflow. Examples: competitive research, tutorial writing, API audits, monthly reporting. - **Reviews** — automated code review rules that run against every change. Define what to check for in `.deepreview` configs, then run `/review`. Catches regressions, style issues, doc drift, security problems. From 915e4b91bdc55b15cfcf36db95bf54f734e522a0 Mon Sep 17 00:00:00 2001 From: Noah Horton Date: Thu, 9 Apr 2026 20:06:29 -0600 Subject: [PATCH 12/12] fix: sync skill bodies and add setup step to new_user onboarding Add the "Special case: /deepwork learn after /deepwork:record" section to platform/skill-body.md and Gemini skill to match the Claude skill, fixing the CI test failure. Also add a setup step (uvx deepwork setup) as the first action in new_user onboarding. Co-Authored-By: Claude Opus 4.6 (1M context) --- AGENTS.md | 7 +++++-- platform/skill-body.md | 9 +++++++++ plugins/claude/skills/new_user/SKILL.md | 10 ++++++++++ plugins/gemini/skills/deepwork/SKILL.md | 9 +++++++++ 4 files changed, 33 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 2339a91f..bd3eef89 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -138,12 +138,13 @@ uv run pytest # Run tests ### 1. Plugin Installation Users install the DeepWork plugin for their AI agent CLI: ``` -claude plugin marketplace add Unsupervisedcom/deepwork -claude plugin install deepwork@deepwork-plugins +claude plugin marketplace add Unsupervisedcom/deepwork && claude plugin install deepwork@deepwork-plugins && claude "/deepwork:new_user" ``` The plugin provides: - `/deepwork` skill for invoking workflows - `/review` and `/configure_reviews` skills for automated reviews +- `/new_user` skill for guided onboarding +- `/record` skill for "watch and learn" workflow creation - MCP server configuration (`uvx deepwork serve`) - Hooks for workflow enforcement @@ -222,6 +223,8 @@ deepwork/ │ │ │ ├── deepreviews/SKILL.md │ │ │ ├── deepwork/SKILL.md │ │ │ ├── deepschema/SKILL.md +│ │ │ ├── new_user/SKILL.md +│ │ │ ├── record/SKILL.md │ │ │ └── review/SKILL.md │ │ ├── hooks/ # hooks.json, post_commit_reminder.sh, post_compact.sh, startup_context.sh, deepschema_write.sh │ │ └── .mcp.json # MCP server config diff --git a/platform/skill-body.md b/platform/skill-body.md index a464ab96..57c916ea 100644 --- a/platform/skill-body.md +++ b/platform/skill-body.md @@ -66,3 +66,12 @@ When the user invokes `/deepwork`, parse their intent: - **Explicit workflow**: `/deepwork ` → start the `` workflow - **General request**: `/deepwork ` → infer best match from available workflows - **No context**: `/deepwork` alone → ask user to choose from available workflows + +### Special case: `/deepwork learn` after `/deepwork:record` + +If the user invokes `/deepwork learn` and `/deepwork:record` was used earlier in this +conversation, the session captured a new workflow from scratch — there is no existing job +to learn from. Instead of starting the `learn` workflow, start the `new_job` workflow +(`job_name: "deepwork_jobs"`, `workflow_name: "new_job"`) with a goal summarizing the +workflow the user recorded. Use the conversation history as the primary input for defining +the job's steps, inputs, and outputs. diff --git a/plugins/claude/skills/new_user/SKILL.md b/plugins/claude/skills/new_user/SKILL.md index 33247426..0efe2ddb 100644 --- a/plugins/claude/skills/new_user/SKILL.md +++ b/plugins/claude/skills/new_user/SKILL.md @@ -10,6 +10,16 @@ Guide a new user through what DeepWork can do and help them get started. ## Flow +### 0. Run setup + +Before anything else, run the setup command to ensure the user's environment is configured: + +```bash +uvx deepwork setup +``` + +This configures Claude Code settings (marketplace, plugin, MCP permissions, auto-update). Proceed regardless of the output. + ### 1. GitHub star (optional) Check if the `gh` CLI is installed by running `which gh`. diff --git a/plugins/gemini/skills/deepwork/SKILL.md b/plugins/gemini/skills/deepwork/SKILL.md index 9fc2244e..69b61ba5 100644 --- a/plugins/gemini/skills/deepwork/SKILL.md +++ b/plugins/gemini/skills/deepwork/SKILL.md @@ -71,3 +71,12 @@ When the user invokes `/deepwork`, parse their intent: - **Explicit workflow**: `/deepwork ` → start the `` workflow - **General request**: `/deepwork ` → infer best match from available workflows - **No context**: `/deepwork` alone → ask user to choose from available workflows + +### Special case: `/deepwork learn` after `/deepwork:record` + +If the user invokes `/deepwork learn` and `/deepwork:record` was used earlier in this +conversation, the session captured a new workflow from scratch — there is no existing job +to learn from. Instead of starting the `learn` workflow, start the `new_job` workflow +(`job_name: "deepwork_jobs"`, `workflow_name: "new_job"`) with a goal summarizing the +workflow the user recorded. Use the conversation history as the primary input for defining +the job's steps, inputs, and outputs.