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/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/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/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/doc/architecture.md b/doc/architecture.md
index 8b7ac6b8..4ec73319 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
@@ -382,9 +384,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/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/.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/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/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/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..605d49a0
--- /dev/null
+++ b/plugins/claude/skills/new_user/.deepschema.SKILL.md.yml
@@ -0,0 +1,50 @@
+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, 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
+ 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..0efe2ddb
--- /dev/null
+++ b/plugins/claude/skills/new_user/SKILL.md
@@ -0,0 +1,67 @@
+---
+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
+
+### 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`.
+
+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 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. 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.
+- **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..63acf782
--- /dev/null
+++ b/plugins/claude/skills/record/.deepschema.SKILL.md.yml
@@ -0,0 +1,65 @@
+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`.
+
+ # 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.
+
+ # 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/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.
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..3924c847
--- /dev/null
+++ b/specs/deepwork/cli_plugins/PLUG-REQ-002-record-skill.md
@@ -0,0 +1,52 @@
+# 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.
+
+### 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.
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/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/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..da3610a8 100644
--- a/src/deepwork/deepschema/review_bridge.py
+++ b/src/deepwork/deepschema/review_bridge.py
@@ -189,6 +189,11 @@ def _add(raw_path: str, description: str | None, source_field: str) -> None:
)
)
+ # 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
# exist without bloating the prompt.
diff --git a/src/deepwork/review/instructions.py b/src/deepwork/review/instructions.py
index 2aa1f963..58525aa5 100644
--- a/src/deepwork/review/instructions.py
+++ b/src/deepwork/review/instructions.py
@@ -246,13 +246,18 @@ 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("")
- # 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:
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,
)
)
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.
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:
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
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: