doc-subcontext
/octopus:doc-subcontext writes a focused CLAUDE.md for a single
subdirectory in a monorepo. It captures the conventions, constraints,
and patterns that are specific to that module without repeating
anything the root CLAUDE.md already covers.
What it solves
In a large monorepo, different subdirectories operate under different
rules. The payments module may use a different error-handling pattern
than the fulfillment engine. The API layer may have strict input
validation conventions that don’t apply to internal utilities. When
all of that context lives only in the root CLAUDE.md — or worse,
nowhere — agents and new contributors apply the wrong conventions to
the wrong code.
A per-subdirectory CLAUDE.md solves this by scoping context to where
it applies. The subcontext cross-references the parent rather than
duplicating it, so there’s a single place to update shared rules and
a separate place to capture module-specific ones.
How it works
The command delegates to the doc-subcontext skill, which manages the
full authoring discipline:
- Reads the parent-chain
CLAUDE.mdfiles (from the repo root down to the target directory) to understand what is already covered. - Runs a one-question-at-a-time interview to surface conventions that are genuinely local to the subdirectory.
- Writes a lean
CLAUDE.md(50–100 lines) that cross-references the parent and captures only what is additive or overriding.
Prerequisite: a root CLAUDE.md must exist. If it doesn’t, the
command refuses and directs you to run octopus update first. A
subcontext is only meaningful on top of a root context.
Usage & parameters
/octopus:doc-subcontext <subdirectory path><subdirectory path>— required. Path to the target subdirectory, relative to the repo root (e.g.api/payments,packages/ui). The rootCLAUDE.mdmust already exist.