Document job type classification (standard, library, bespoke)

AGENTS.md

@@ -0,0 +1,86 @@
+# DeepWork - Agent Instructions
+
+This file contains critical instructions for AI agents working on this codebase.
+
+## CRITICAL: Job Type Classification
+
+When creating or modifying jobs in this repository, you MUST understand which type of job you are working with. There are exactly **three types of jobs**, each with a specific location and purpose.
+
+### 1. Standard Jobs (`src/deepwork/standard_jobs/`)
+
+**What they are**: Core jobs that are part of the DeepWork framework itself. These get automatically installed to every target repository when users run `deepwork install`.
+
+**Location**: `src/deepwork/standard_jobs/[job_name]/`
+
+**Current standard jobs**:
+- `deepwork_jobs` - Core job management (define, implement, learn)
+- `deepwork_rules` - Rules enforcement system
+
+**Editing rules**:
+- Source of truth is ALWAYS in `src/deepwork/standard_jobs/`
+- NEVER edit the installed copies in `.deepwork/jobs/` directly
+- After editing, run `deepwork install --platform claude` to sync
+
+### 2. Library Jobs (`library_jobs/`)
+
+**What they are**: Example or reusable jobs that any repository is welcome to use, but are NOT auto-installed. Users must explicitly copy or import these into their projects.
+
+**Location**: `library_jobs/[job_name]/`
+
+**Examples** (potential):
+- Competitive research workflows
+- Code review processes
+- Documentation generation
+- Release management
+
+**Editing rules**:
+- Edit directly in `library_jobs/[job_name]/`
+- These are templates/examples for users to adopt
+- Should be well-documented and self-contained
+
+### 3. Bespoke/Repo Jobs (`.deepwork/jobs/`)
+
+**What they are**: Jobs that are ONLY for this specific repository (the DeepWork repo itself). These are not distributed to users and exist only for internal development workflows.
+
+**Location**: `.deepwork/jobs/[job_name]/` (but NOT if the job also exists in `src/deepwork/standard_jobs/`)
+
+**Identifying bespoke jobs**: A job in `.deepwork/jobs/` is bespoke ONLY if it does NOT have a corresponding directory in `src/deepwork/standard_jobs/`.
+
+**Editing rules**:
+- Edit directly in `.deepwork/jobs/[job_name]/`
+- These are private to this repository
+- Run `deepwork sync` after changes to regenerate skills
+
+## IMPORTANT: When Creating New Jobs
+
+Before creating any new job, you MUST determine which type it should be. **If there is any ambiguity**, ask the user a structured question to clarify:
+
+```
+Which type of job should this be?
+1. Standard Job - Part of the DeepWork framework, auto-installed to all users
+2. Library Job - Reusable example that users can optionally adopt
+3. Bespoke Job - Only for this repository's internal workflows
+```
+
+### Decision Guide
+
+| Question | If Yes → |
+|----------|----------|
+| Should this be installed automatically when users run `deepwork install`? | Standard Job |
+| Is this a reusable pattern that other repos might want to copy? | Library Job |
+| Is this only useful for developing DeepWork itself? | Bespoke Job |
+
+## File Structure Summary
+
+```
+deepwork/
+├── src/deepwork/standard_jobs/    # Standard jobs (source of truth)
+│   ├── deepwork_jobs/
+│   └── deepwork_rules/
+├── library_jobs/                   # Library/example jobs
+│   └── [example_job]/
+└── .deepwork/jobs/                 # Installed standard jobs + bespoke jobs
+    ├── deepwork_jobs/              # ← Installed copy, NOT source of truth
+    ├── deepwork_rules/             # ← Installed copy, NOT source of truth
+    └── [bespoke_job]/              # ← Source of truth for bespoke only
+```

claude.md

@@ -42,10 +42,12 @@ deepwork/
 │   │   ├── claude/
 │   │   ├── gemini/
 │   │   └── copilot/
-│   ├── standard_jobs/    # Built-in job definitions
-│   │   └── deepwork_jobs/
+│   ├── standard_jobs/    # Built-in job definitions (auto-installed)
+│   │   ├── deepwork_jobs/
+│   │   └── deepwork_rules/
 │   ├── schemas/          # Job definition schemas
 │   └── utils/            # Utilities (fs, git, yaml, validation)
+├── library_jobs/         # Reusable example jobs (not auto-installed)
 ├── tests/                # Test suite
 ├── doc/                  # Documentation
 └── doc/architecture.md   # Detailed architecture document
@@ -182,16 +184,24 @@ my-project/
 6. **No Auto-Commit**: DO NOT automatically commit changes to git. Let the user review and commit changes themselves.
 7. **Documentation Sync**: CRITICAL - When making implementation changes, always update `doc/architecture.md` and `README.md` to reflect those changes. The architecture document must stay in sync with the actual codebase (terminology, file paths, structure, behavior, etc.).
 
-## CRITICAL: Editing Standard Jobs
+## CRITICAL: Job Types and Where to Edit
+
+**See `AGENTS.md` for the complete job classification guide.** This repository has THREE types of jobs:
+
+| Type | Location | Purpose |
+|------|----------|---------|
+| **Standard Jobs** | `src/deepwork/standard_jobs/` | Framework core, auto-installed to users |
+| **Library Jobs** | `library_jobs/` | Reusable examples users can adopt |
+| **Bespoke Jobs** | `.deepwork/jobs/` (if not in standard_jobs) | This repo's internal workflows only |
+
+### Editing Standard Jobs
 
 **Standard jobs** (like `deepwork_jobs` and `deepwork_rules`) are bundled with DeepWork and installed to user projects. They exist in THREE locations:
 
 1. **Source of truth**: `src/deepwork/standard_jobs/[job_name]/` - The canonical source files
 2. **Installed copy**: `.deepwork/jobs/[job_name]/` - Installed by `deepwork install`
 3. **Generated skills**: `.claude/skills/[job_name].[step].md` - Generated from installed jobs
 
-### Editing Workflow for Standard Jobs
-
 **NEVER edit files in `.deepwork/jobs/` or `.claude/skills/` for standard jobs directly!**
 
 Instead, follow this workflow:
@@ -205,13 +215,13 @@ Instead, follow this workflow:
 
 3. **Verify** the changes propagated correctly to all locations
 
-### How to Identify Standard Jobs
+### How to Identify Job Types
 
-Standard jobs are defined in `src/deepwork/standard_jobs/`. Currently:
-- `deepwork_jobs` - Core job management commands (define, implement, refine)
-- `deepwork_rules` - Rules enforcement system
+- **Standard jobs**: Exist in `src/deepwork/standard_jobs/` (currently: `deepwork_jobs`, `deepwork_rules`)
+- **Library jobs**: Exist in `library_jobs/`
+- **Bespoke jobs**: Exist ONLY in `.deepwork/jobs/` with no corresponding standard_jobs entry
 
-If a job exists in `src/deepwork/standard_jobs/`, it is a standard job and MUST be edited there.
+**When creating a new job, always clarify which type it should be.** If uncertain, ask the user.
 
 ## Success Metrics