From beagle-docs
Generates first-draft Reference or How-To technical documentation from code analysis, saving to docs/drafts/ for review before publishing.
npx claudepluginhub existential-birds/beagle --plugin beagle-docsThis skill uses the workspace's default tool permissions.
Generate Reference or How-To documentation drafts to `docs/drafts/` for review before publishing.
Creates isolated Git worktrees for feature branches with prioritized directory selection, gitignore safety checks, auto project setup for Node/Python/Rust/Go, and baseline verification.
Executes implementation plans in current session by dispatching fresh subagents per independent task, with two-stage reviews: spec compliance then code quality.
Dispatches parallel agents to independently tackle 2+ tasks like separate test failures or subsystems without shared state or dependencies.
Generate Reference or How-To documentation drafts to docs/drafts/ for review before publishing.
/beagle-docs:draft-docs "Document the authentication middleware"
Before parsing input, gather project context:
# Check for existing docs structure
ls -la docs/ 2>/dev/null || echo "No docs/ directory found"
# Identify documentation framework
ls docs/navigation.json docs/mint.json docs/docusaurus.config.js docs/mkdocs.yml 2>/dev/null | head -1
# Check for existing drafts
ls docs/drafts/*.md 2>/dev/null || echo "No existing drafts"
# Get recent code changes for context
git diff --name-only $(git merge-base HEAD main)..HEAD 2>/dev/null | head -20
Capture:
docs/ subdirectories presentnavigation.json, mint.json, or other configExtract from the prompt:
| Keywords | Type | Skill |
|---|---|---|
| "how to", "guide", "steps", "configure", "set up" | How-To | howto-docs |
| "API", "reference", "parameters", "function", "endpoint" | Reference | reference-docs |
If ambiguous, ask: "Should this be a Reference doc (technical lookup) or How-To guide (task completion)?"
Always load both:
beagle-docs:docs-style - Core writing principlesbeagle-docs:reference-docs for Referencebeagle-docs:howto-docs for How-ToSearch the codebase for relevant code:
Gather:
Apply the loaded skills to generate documentation:
For Reference docs:
reference-docs template structureFor How-To docs:
howto-docs template structureCreate output path:
docs/drafts/{slug}.mdwebsocket-api.mdEnsure directory exists:
mkdir -p docs/drafts
Write the draft file
Report to user:
## Draft Created
**File:** `docs/drafts/{slug}.md`
**Type:** Reference | How-To
**Based on:** [list of analyzed symbols/files]
### Next Steps
1. Review the draft for accuracy
2. Add any missing context or examples
3. When ready, publish with:
/beagle-docs:draft-docs --publish docs/drafts/{slug}.md
Verify draft generation completed successfully:
# Confirm draft file exists
ls -la docs/drafts/{slug}.md
# Validate frontmatter (YAML header)
head -10 docs/drafts/{slug}.md | grep -E "^---$|^title:|^description:"
# Check markdown syntax (if markdownlint available)
markdownlint docs/drafts/{slug}.md 2>/dev/null || echo "markdownlint not available"
Verification Checklist:
docs/drafts/{slug}.mdtitle and descriptionIf any verification fails, report the specific issue and offer to regenerate.
/beagle-docs:draft-docs --publish docs/drafts/websocket-api.md
Read the draft file and extract:
Ask user which section:
Where should this document go?
1. **API Reference** → `docs/api/{slug}.md`
2. **Guides** → `docs/guides/{slug}.md`
3. **How-To** → `docs/how-to/{slug}.md`
4. **Other** → Specify path
mv docs/drafts/{slug}.md {destination}/{slug}.md
Check for docs/navigation.json and update navigation:
Example update:
{
"navigation": [
{
"group": "API Reference",
"pages": [
"api/existing-page",
"api/websocket-api"
]
}
]
}
## Published
**From:** `docs/drafts/{slug}.md`
**To:** `{destination}/{slug}.md`
**Navigation:** Updated `docs/navigation.json`
The document is now live in your docs.
Verify publish completed successfully:
# Confirm file moved to destination
ls -la {destination}/{slug}.md
# Confirm draft removed
ls docs/drafts/{slug}.md 2>/dev/null && echo "WARNING: Draft still exists" || echo "Draft cleaned up"
# Verify navigation updated
grep -q "{slug}" docs/navigation.json && echo "Navigation includes new page" || echo "WARNING: Navigation may need manual update"
# Check markdown syntax at final location
markdownlint {destination}/{slug}.md 2>/dev/null || echo "markdownlint not available"
Verification Checklist:
{destination}/{slug}.mddocs/drafts/If any verification fails, report the specific issue and offer remediation steps.
docs-style skill for every draftdocs/drafts/ - never directly to final location