Document job type classification (standard, library, bespoke)

Add AGENTS.md with comprehensive documentation of the three job types
and their locations. Update CLAUDE.md to reference the classification
and align the project structure documentation.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: nhorton

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