docs: split docs workflows into a dedicated tool pack

.agents/skills/oat-agent-instructions-analyze/SKILL.md

@@ -77,6 +77,7 @@ or fill in missing evidence gaps on its own.
 
 ```bash
 SCRIPT_DIR=".agents/skills/oat-agent-instructions-analyze/scripts"
+TRACKING_SCRIPT=".oat/scripts/resolve-tracking.sh"
 PROVIDERS=$(bash "$SCRIPT_DIR/resolve-providers.sh" --non-interactive)
 # Or with explicit override:
 # PROVIDERS=$(bash "$SCRIPT_DIR/resolve-providers.sh" --providers claude,cursor)
@@ -87,7 +88,7 @@ If running interactively (user invoked the skill directly), omit `--non-interact
 **Resolve analysis mode (delta vs full):**
 
 ```bash
-TRACKING=$(bash "$SCRIPT_DIR/resolve-tracking.sh" read agentInstructions)
+TRACKING=$(bash "$TRACKING_SCRIPT" read agentInstructions)
 ```
 
 - If `TRACKING` is non-empty, extract `commitHash` from the JSON.
@@ -439,11 +440,12 @@ The markdown artifact and companion bundle together are the contract for apply.
 **Update tracking:**
 
 ```bash
-ROOT_TARGET=$(bash "$SCRIPT_DIR/resolve-tracking.sh" root)
+TRACKING_SCRIPT=".oat/scripts/resolve-tracking.sh"
+ROOT_TARGET=$(bash "$TRACKING_SCRIPT" root)
 ROOT_HASH=$(echo "$ROOT_TARGET" | jq -r '.commitHash')
 ROOT_BRANCH=$(echo "$ROOT_TARGET" | jq -r '.baseBranch')
 
-bash "$SCRIPT_DIR/resolve-tracking.sh" write \
+bash "$TRACKING_SCRIPT" write \
   agentInstructions \
   "$ROOT_HASH" \
   "$ROOT_BRANCH" \
@@ -493,6 +495,6 @@ Next step: Run oat-agent-instructions-apply to act on these findings.
 - Bundle summary template: `references/bundle-summary-template.md`
 - Bundle manifest template: `references/recommendations-manifest-template.yaml`
 - Recommendation pack template: `references/recommendation-pack-template.md`
-- Tracking script: `scripts/resolve-tracking.sh`
+- Tracking script: `.oat/scripts/resolve-tracking.sh`
 - Provider resolution: `scripts/resolve-providers.sh`
 - File discovery: `scripts/resolve-instruction-files.sh`

.agents/skills/oat-agent-instructions-apply/SKILL.md

@@ -156,6 +156,7 @@ Then stop.
 
 ```bash
 SCRIPT_DIR=".agents/skills/oat-agent-instructions-analyze/scripts"
+TRACKING_SCRIPT=".oat/scripts/resolve-tracking.sh"
 PROVIDERS=$(bash "$SCRIPT_DIR/resolve-providers.sh" --non-interactive)
 ```
 
@@ -460,12 +461,12 @@ PR creation failed. To create manually:
 **Update tracking:**
 
 ```bash
-SCRIPT_DIR=".agents/skills/oat-agent-instructions-analyze/scripts"
-ROOT_TARGET=$(bash "$SCRIPT_DIR/resolve-tracking.sh" root)
+TRACKING_SCRIPT=".oat/scripts/resolve-tracking.sh"
+ROOT_TARGET=$(bash "$TRACKING_SCRIPT" root)
 ROOT_HASH=$(echo "$ROOT_TARGET" | jq -r '.commitHash')
 ROOT_BRANCH=$(echo "$ROOT_TARGET" | jq -r '.baseBranch')
 
-bash "$SCRIPT_DIR/resolve-tracking.sh" write \
+bash "$TRACKING_SCRIPT" write \
   agentInstructionsApply \
   "$ROOT_HASH" \
   "$ROOT_BRANCH" \
@@ -503,4 +504,4 @@ Apply complete.
 - Analysis artifact: `.oat/repo/analysis/agent-instructions-*.md`
 - Templates: `references/instruction-file-templates/`
 - Apply plan template: `references/apply-plan-template.md`
-- Tracking script: `scripts/resolve-tracking.sh` (symlink to analyze skill)
+- Tracking script: `.oat/scripts/resolve-tracking.sh`

.agents/skills/oat-docs-analyze/SKILL.md

@@ -92,7 +92,7 @@ Prefer the OAT docs app when multiple MkDocs apps exist and one is clearly the a
 Resolve tracking and analysis mode using the shared helper:
 
 ```bash
-TRACKING_SCRIPT=".agents/skills/oat-agent-instructions-analyze/scripts/resolve-tracking.sh"
+TRACKING_SCRIPT=".oat/scripts/resolve-tracking.sh"
 TRACKING=$(bash "$TRACKING_SCRIPT" read docs 2>/dev/null || true)
 ```
 
@@ -307,7 +307,7 @@ Populate the artifact with:
 Update docs tracking using the shared helper:
 
 ```bash
-TRACKING_SCRIPT=".agents/skills/oat-agent-instructions-analyze/scripts/resolve-tracking.sh"
+TRACKING_SCRIPT=".oat/scripts/resolve-tracking.sh"
 ROOT_TARGET=$(bash "$TRACKING_SCRIPT" root)
 ROOT_HASH=$(echo "$ROOT_TARGET" | jq -r '.commitHash')
 ROOT_BRANCH=$(echo "$ROOT_TARGET" | jq -r '.baseBranch')
@@ -352,4 +352,4 @@ Next step: Run oat-docs-apply to act on these findings.
 - Analysis artifact template: `references/analysis-artifact-template.md`
 - Quality checklist: `references/quality-checklist.md`
 - Directory criteria: `references/directory-assessment-criteria.md`
-- Shared tracking helper: `.agents/skills/oat-agent-instructions-analyze/scripts/resolve-tracking.sh`
+- Shared tracking helper: `.oat/scripts/resolve-tracking.sh`

.agents/skills/oat-docs-apply/SKILL.md

@@ -301,7 +301,7 @@ PR creation failed. To create manually:
 Update shared tracking:
 
 ```bash
-TRACKING_SCRIPT=".agents/skills/oat-agent-instructions-analyze/scripts/resolve-tracking.sh"
+TRACKING_SCRIPT=".oat/scripts/resolve-tracking.sh"
 ROOT_TARGET=$(bash "$TRACKING_SCRIPT" root)
 ROOT_HASH=$(echo "$ROOT_TARGET" | jq -r '.commitHash')
 ROOT_BRANCH=$(echo "$ROOT_TARGET" | jq -r '.baseBranch')
@@ -336,4 +336,4 @@ Next step: Re-run oat-docs-analyze if you want a post-apply verification artifac
 ## References
 
 - Apply plan template: `references/apply-plan-template.md`
-- Shared tracking helper: `.agents/skills/oat-agent-instructions-analyze/scripts/resolve-tracking.sh`
+- Shared tracking helper: `.oat/scripts/resolve-tracking.sh`

.agents/skills/oat-doctor/SKILL.md

@@ -86,7 +86,7 @@ Read `$ARGUMENTS`:
 TOOLS_JSON=$(oat tools list --json --scope all 2>/dev/null || echo '{"tools":[]}')
 ```
 
-Parse the JSON output. Each tool has: `name`, `type` (skill/agent), `scope` (project/user), `version`, `bundledVersion`, `pack` (core/ideas/workflows/utility/custom), `status` (current/outdated/newer/not-bundled).
+Parse the JSON output. Each tool has: `name`, `type` (skill/agent), `scope` (project/user), `version`, `bundledVersion`, `pack` (core/docs/ideas/workflows/utility/project-management/research/custom), `status` (current/outdated/newer/not-bundled).
 
 ### Step 2: Check for Outdated Skills
 
@@ -167,13 +167,27 @@ Ideas pack skills:
 
 - oat-idea-new, oat-idea-ideate, oat-idea-summarize, oat-idea-scratchpad
 
-Utility pack skills:
+Docs pack skills:
 
-- create-agnostic-skill, oat-agent-instructions-analyze, oat-agent-instructions-apply
+- oat-agent-instructions-analyze, oat-agent-instructions-apply
 - oat-docs-analyze, oat-docs-apply
+
+Utility pack skills:
+
+- create-agnostic-skill
 - oat-repo-maintainability-review, oat-review-provide
 - oat-review-receive, oat-review-receive-remote
 
+Project management pack skills:
+
+- oat-pjm-add-backlog-item, oat-pjm-update-repo-reference
+- oat-pjm-review-backlog
+
+Research pack skills:
+
+- analyze, compare, deep-research
+- skeptic, synthesize
+
 For each pack, determine:
 
 - **Installed:** all pack skills found in installed tools list
@@ -205,9 +219,12 @@ OAT ▸ DOCTOR SUMMARY
 | Pack      | Scope   | Skills | Status   |
 | --------- | ------- | ------ | -------- |
 | core      | user    | 2/2    | current  |
+| docs      | project | 4/4    | current  |
 | workflows | project | 26/26  | current  |
 | ideas     | user    | 4/4    | current  |
-| utility   | project | 9/9    | outdated |
+| project-management | project | 3/3 | current |
+| research  | project | 5/5    | current  |
+| utility   | project | 5/5    | outdated |
 
 ## Outdated Skills
 
@@ -217,8 +234,12 @@ OAT ▸ DOCTOR SUMMARY
 
 ## Available But Not Installed
 
-- **utility** pack: oat-docs-analyze, oat-docs-apply (2 skills available)
-  → Run: oat tools update --scope {scope}
+- **docs** pack: oat-docs-analyze, oat-docs-apply, oat-agent-instructions-analyze, oat-agent-instructions-apply (4 skills available)
+  → Run: oat tools install docs --scope {scope}
+- **project-management** pack: oat-pjm-add-backlog-item, oat-pjm-update-repo-reference, oat-pjm-review-backlog (3 skills available)
+  → Run: oat tools install project-management --scope {scope}
+- **research** pack: analyze, compare, deep-research, skeptic, synthesize (5 skills available)
+  → Run: oat tools install research --scope {scope}
 
 ## Configuration
 

.agents/skills/oat-repo-knowledge-index/SKILL.md

@@ -675,11 +675,11 @@ Generated from commit: {MERGE_BASE_SHA}"
 Record the knowledge index run in the shared tracking manifest:
 
 ```bash
-ROOT_TARGET=$(bash .agents/skills/oat-agent-instructions-analyze/scripts/resolve-tracking.sh root)
+ROOT_TARGET=$(bash .oat/scripts/resolve-tracking.sh root)
 ROOT_HASH=$(echo "$ROOT_TARGET" | jq -r '.commitHash')
 ROOT_BRANCH=$(echo "$ROOT_TARGET" | jq -r '.baseBranch')
 
-bash .agents/skills/oat-agent-instructions-analyze/scripts/resolve-tracking.sh \
+bash .oat/scripts/resolve-tracking.sh \
   write knowledgeIndex "$ROOT_HASH" "$ROOT_BRANCH" full \
   --artifact-path ".oat/repo/knowledge/"
 ```

.agents/skills/oat-agent-instructions-analyze/scripts/resolve-tracking.sh → .oat/scripts/resolve-tracking.sh

@@ -29,11 +29,9 @@
 
 set -euo pipefail
 
-# Resolve repo root and tracking file path
 REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
 TRACKING_FILE="${REPO_ROOT}/.oat/tracking.json"
 
-# Ensure jq is available
 if ! command -v jq &>/dev/null; then
   echo "Error: jq is required but not found in PATH" >&2
   exit 1
@@ -139,7 +137,6 @@ cmd_write() {
   local mode="${4:?Missing mode}"
   shift 4
 
-  # Parse optional --artifact-path flag before variadic formats
   local artifact_path=""
   if [[ "${1:-}" == "--artifact-path" ]]; then
     artifact_path="${2:?Missing artifact path value after --artifact-path}"
@@ -148,7 +145,6 @@ cmd_write() {
 
   local formats=("$@")
 
-  # Normalize tracking target to root branch tip to keep commitHash resolvable.
   local normalized_branch normalized_hash
   normalized_branch="$(detect_root_branch)"
   normalized_hash="$(resolve_root_commit_hash "$normalized_branch")"
@@ -160,7 +156,6 @@ cmd_write() {
   base_branch="$normalized_branch"
   commit_hash="$normalized_hash"
 
-  # Build formats JSON array
   local formats_json="[]"
   if [[ ${#formats[@]} -gt 0 ]]; then
     formats_json=$(printf '%s\n' "${formats[@]}" | jq -R . | jq -s .)
@@ -169,7 +164,6 @@ cmd_write() {
   local timestamp
   timestamp="$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
 
-  # Read existing or initialize
   local existing
   if [[ -f "$TRACKING_FILE" ]] && jq empty "$TRACKING_FILE" 2>/dev/null; then
     existing="$(cat "$TRACKING_FILE")"
@@ -178,7 +172,6 @@ cmd_write() {
     existing='{"version":1}'
   fi
 
-  # Merge operation entry (include artifactPath only if provided)
   if [[ -n "$artifact_path" ]]; then
     echo "$existing" | jq \
       --arg op "$operation" \
@@ -216,30 +209,25 @@ cmd_write() {
   echo "Updated $TRACKING_FILE [$operation]"
 }
 
-# Dispatch subcommand
 case "${1:-}" in
   init)
-    cmd_init
+    shift
+    cmd_init "$@"
     ;;
   read)
     shift
     cmd_read "$@"
     ;;
   root)
-    cmd_root
+    shift
+    cmd_root "$@"
     ;;
   write)
     shift
     cmd_write "$@"
     ;;
   *)
     echo "Usage: resolve-tracking.sh {init|read|root|write} [args...]" >&2
-    echo "" >&2
-    echo "Commands:" >&2
-    echo "  init                                              Create tracking.json if missing" >&2
-    echo "  read <operation>                                  Read operation entry" >&2
-    echo "  root                                              Print root branch + commit as JSON" >&2
-    echo "  write <op> <hash> <branch> <mode> [--artifact-path <p>] [fmts]" >&2
-    exit 1
+    exit 2
     ;;
 esac

AGENTS.md

@@ -138,7 +138,7 @@ Projects live in `.oat/projects/<scope>/<project>/` with:
 - Core files: `state.md`, `discovery.md`, `spec.md`, `design.md`, `plan.md`, `implementation.md`
 - Optional: `reviews/`, `pr/`
 
-### Utility Skill Additions
+### Docs Pack Workflows
 
 - `oat-docs-analyze` - Analyze a docs surface for `index.md` contract coverage, nav drift, and docs app readiness.
 - `oat-docs-apply` - Apply approved docs-analysis recommendations with branch, nav-sync, and PR workflow support.

README.md

@@ -175,7 +175,7 @@ pnpm run cli -- tools update --all
 
 Notes:
 
-- `tools install` installs OAT skills/agents/templates/scripts by pack (`core`, `ideas`, `workflows`, `utility`, `research`) and auto-syncs provider views. The core pack (diagnostics, docs) always installs at user scope.
+- `tools install` installs OAT skills/agents/templates/scripts by pack (`core`, `docs`, `ideas`, `workflows`, `utility`, `project-management`, `research`) and auto-syncs provider views. The core pack (diagnostics, passive docs access) always installs at user scope.
 - `tools outdated` shows which installed tools have available updates.
 - `tools update --all` updates all outdated tools to bundled versions.
 - Use `--no-sync` on any mutation command to skip auto-sync.

apps/oat-docs/docs/guide/cli-reference.md

@@ -55,7 +55,7 @@ Use the `oat tools` group to manage bundled OAT assets:
 - `oat tools list` - list installed tools, versions, pack membership, and update state
 - `oat tools info <name>` - inspect one installed skill or agent
 - `oat tools outdated` - show only assets with available updates
-- `oat tools install` - install bundled packs such as `core`, `ideas`, `workflows`, `utility`, `project-management`, or `research`
+- `oat tools install` - install bundled packs such as `core`, `docs`, `ideas`, `workflows`, `utility`, `project-management`, or `research`
 - `oat tools update` - update a named tool, a whole pack, or everything
 - `oat tools remove` - remove installed assets
 

apps/oat-docs/docs/guide/documentation/quickstart.md

@@ -15,7 +15,7 @@ If you are developing inside the OAT repo itself, replace `oat ...` with
 
 - a docs app scaffolded with OAT defaults (Fumadocs or MkDocs)
 - `index.md`-driven navigation
-- docs analysis and apply skills installed via the utility pack
+- docs analysis and apply skills installed via the docs pack
 - a repeatable workflow for finding gaps, verifying claims, and applying docs changes
 
 ## 1. Initialize OAT in the repo
@@ -28,19 +28,27 @@ This sets up the base OAT structure used by the CLI and installed tool packs.
 
 ## 2. Install the docs workflow skills
 
-Fastest direct path:
+Preferred direct path:
 
 ```bash
-oat init tools utility
+oat tools install docs
 ```
 
 Interactive path:
 
 ```bash
-oat init tools
+oat tools install
 ```
 
-The utility pack installs `oat-docs-analyze` and `oat-docs-apply`.
+Legacy pack-specific path:
+
+```bash
+oat init tools docs
+```
+
+The docs pack installs `oat-docs-analyze`, `oat-docs-apply`,
+`oat-agent-instructions-analyze`, and `oat-agent-instructions-apply`. For this
+quickstart, the docs pair is the part you need immediately.
 
 ## 3. Scaffold the docs app
 
@@ -140,7 +148,7 @@ Important:
 ## Typical loop
 
 1. `oat init --scope project`
-2. `oat init tools utility`
+2. `oat tools install docs`
 3. `oat docs init --app-name my-docs`
 4. (optional) `oat docs migrate --docs-dir docs --config mkdocs.yml --apply`
 5. Author docs with `index.md` + `## Contents`

apps/oat-docs/docs/guide/documentation/workflows.md

@@ -8,6 +8,9 @@ description: 'Docs CLI helpers and skills for analysis and controlled documentat
 OAT’s docs workflow combines deterministic CLI helpers with higher-judgment
 skills for analysis and controlled updates.
 
+Install the workflow skills with `oat tools install docs` (preferred) or
+`oat init tools docs` before using the analyze/apply flow in a new repo.
+
 ## Docs workflow pieces
 
 ### CLI helpers

apps/oat-docs/docs/guide/getting-started.md

@@ -36,7 +36,7 @@ After core initialization completes, `oat init` can enter an interactive guided
 
 **Steps (each independently skippable):**
 
-1. **Tool packs** — install OAT tool packs. The core pack (diagnostics, docs) is checked by default and always installs at user scope. Other packs (ideas, workflows, utility, research) install at project scope.
+1. **Tool packs** — install OAT tool packs. The core pack (diagnostics, passive docs access) is checked by default and always installs at user scope. Other packs (`docs`, `ideas`, `workflows`, `utility`, `project-management`, `research`) install at project scope.
 2. **Local paths** — multi-select from default gitignored artifact paths (analysis, PR, reviews, ideas). Pre-existing paths are pre-checked; only new paths are added.
 3. **Provider sync** — sync provider project views via `oat sync --scope project`.
 4. **Summary** — reports what was configured: active providers, tool packs status, local paths added/existing, and provider sync status. Includes suggested next steps.