docs-profile

Profile the documentation repository: $ARGUMENTS

$ARGUMENTS is an optional repo path (default: the current working directory), optionally followed by --inline. The --inline token is passed when /document (keyed mode) invokes this flow inline (its Phase 0 case (c)); it switches this command to inline mode — see Phase 5 step 1, step 2, step 6, and Phase 6.

/docs-profile bootstraps or refreshes the machine-readable docs-profile that /document (keyed mode) consumes. It scans a documentation repository, synthesises a .dev-workflows/docs-profile.yml (and complementary CLAUDE.md guidance) that conforms to ${CLAUDE_PLUGIN_ROOT}/references/docs-profiles/docs-profile-schema.md, then writes the result as a reviewable PR — branch + commit + a drafted PR message. It never pushes or auto-merges.

The command is generic — it works on any docs repo. A repo publishing one documentation set gets a single spaces[] entry; a repo publishing several gets one entry per content root, plus the per-space dev-server and lint/build/format commands that go with them.

It does not re-specify changelog or owners rules. Those are owned by the docs-frontmatter skill (+ ${CLAUDE_PLUGIN_ROOT}/references/docs-profiles/changelog-guidelines.md, ${CLAUDE_PLUGIN_ROOT}/references/docs-profiles/default-owners.txt); the profile's frontmatter: fields are pointers only.

For one-off doc edits use direct mode; for keyed feature documentation use /document (keyed mode).

---

Phase 0 — Resolve and validate the target repo

1. Resolve the repo path. Take the first token of $ARGUMENTS as the target path; if $ARGUMENTS is empty, default to the current working directory. Resolve it to an absolute path and record it as <repo>. Treat a --inline token (in any position) as the inline-mode flag, not a path; record inline = true when present.

2. Validate it is a writeable git work tree:

   • git -C <repo> rev-parse --is-inside-work-tree must print true. If it errors or prints anything else, stop with the named error: NOT_A_GIT_WORKTREE: <repo> is not inside a git work tree.
   • test -w <repo> must succeed. If not, stop with the named error: REPO_NOT_WRITEABLE: <repo> is not writeable.
   • Resolve and record the repo's git root: git -C <repo> rev-parse --show-toplevel. All later detection and writes are relative to this root.

3. Detect docs-repo signals under the git root:

   • package.json with any doc script (matching *:start, *:build, *:lint, docs:*, prettier),
   • a .docstack/ directory,
   • a .vale.ini file,
   • any */_content/ directory (e.g. cloud/_content, self-hosted/_content),
   • any _snippets/ directory.

   If ≥ 1 signal is present → proceed silently to Phase 1. If 0 signals are present → ask before continuing:

   "No documentation-repo signals detected under <repo> (checked: package.json doc scripts, .docstack/, .vale.ini, */_content/, _snippets/). Profile it anyway?"
   choices: ["Proceed — I confirm this is a docs repo (Recommended)", "Cancel — point me at a docs repo first"]
   

   Default = Proceed. On Cancel, stop and report.

---