Revamp dot-agents work-item workflow and onboarding

.agents/.gitignore

@@ -1,6 +1,7 @@
 # External reference repositories cloned for analysis
 # These are typically large and should not be committed
-reference/
+references/*
+!references/.gitkeep
 
 # Backup directory created during install --force
-../.dot-agents-backup/
+.dot-agents-backup/

.agents/references/.gitkeep

@@ -0,0 +1 @@
+# Keep .agents/references/ present on fresh installs.

.agents/scripts/sync.sh

@@ -54,15 +54,17 @@ All options are passed through to the upstream install.sh script.
 
 Options:
   --dry-run         Show what would happen without making changes
+  --diff            Preview pending changes without writing; exit 1 if pending
   --force           Overwrite conflicts (creates backup first)
+  --write-conflicts Create file.dot-agents.md/file.ext.dot-agents.new conflicts
   --interactive     Prompt for each conflict
   --yes             Skip confirmation prompts
   --version         Show version and installation info
   --help            Show this help message
 
 Examples:
   # Preview changes
-  .agents/scripts/sync.sh --dry-run
+  .agents/scripts/sync.sh --diff
 
   # Force update with backup
   .agents/scripts/sync.sh --force

.agents/skills/AGENTS.md

@@ -48,6 +48,8 @@ The description determines when the skill gets loaded:
 3. **Define workflows** - Step-by-step processes work best
 4. **Add checklists** - Help ensure nothing is missed
 5. **Reference patterns** - Point to existing code/files
+6. **Keep workflow skills durable** - Put reusable templates in `assets/` and runnable helpers in `scripts/`
+7. **Avoid runner-specific concepts** - Prefer work items and handoff prompts over assuming a specific agent runtime
 
 ## Testing Skills
 
@@ -63,6 +65,7 @@ Verify your skill by loading it and checking:
 | Skill | Purpose |
 | ----- | ------- |
 | `adapt` | Analyze project and fill in AGENTS.md after installation |
-| `ralph` | Autonomous multi-iteration implementation using handoff loops |
-| `research` | Deep research on technical topics, saves to `.agents/research/` |
+| `agent-work` | Create and maintain `.agents/work/` work items |
+| `feature-planning` | Turn context into plans and paste-ready handoff prompts |
+| `research` | Research technical topics, saving work-local or reusable findings |
 | `tmux` | Manage background processes using tmux windows for servers and long-running tasks |

.agents/skills/adapt/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: adapt
-description: "Analyze project and fill in AGENTS.md. Use when adapting dot-agents to a new project, after initial installation."
+description: "Analyzes a project and fills in AGENTS.md. Use after installing dot-agents or when project commands and conventions change. Triggers on: adapt, setup AGENTS, customize AGENTS."
 ---
 
 # Adapt Skill
@@ -28,12 +28,13 @@ Run this skill after installing dot-agents into a new project to customize the c
    - List detected tech stack
    - Extract commands from package.json scripts, Cargo.toml, Makefile, etc.
    - Note any project-specific conventions observed
+   - Keep the `.agents/work/` and handoff-prompt workflow guidance intact
 
 ## Example Output
 
 After running, AGENTS.md should have these sections filled in:
 
-```markdown
+````markdown
 ## Overview
 
 my-awesome-app - A Next.js web application with PostgreSQL backend
@@ -72,6 +73,13 @@ pnpm format
 - Components in src/components/
 - API routes in src/app/api/
 
+## Agent Work
+
+- Durable work lives in `.agents/work/<category>/<slug>/`
+- Use `.agents/research/` only for reusable findings
+- Ask for a handoff prompt before starting a fresh implementation thread
+````
+
 ## Checklist
 
 - [ ] Read package.json/Cargo.toml/go.mod for project name and scripts
@@ -80,3 +88,4 @@ pnpm format
 - [ ] Check for Makefile, Justfile, or task runners
 - [ ] Look for .eslintrc, .prettierrc, rustfmt.toml for style configs
 - [ ] Update AGENTS.md with findings
+- [ ] Preserve the dot-agents work-item workflow unless the user asks for a custom one