Major improvements to docs:create UX for both Claude Code and external tool integration:
**New `docs` CLI command:**
- Add scripts/docs-cli.js - main CLI with subcommand routing
- Add bin field to package.json for `docs` command
- Usage: `docs create` and `docs edit` (cleaner than yarn commands)
**Smart piping detection:**
- Auto-detect when stdout is piped (\!process.stdout.isTTY)
- When piping: automatically output prompt text (no flag needed)
- When interactive: output prompt file path
- --print-prompt flag now optional (auto-enabled when piping)
**Updated help text:**
- Show `docs create` syntax first, yarn as alternative
- Simplify examples with new CLI
- Document smart piping behavior
- Focus on two main workflows: Claude Code vs external agents
**Usage examples:**
# Inside Claude Code - automatic execution
docs create drafts/new-feature.md
# Pipe to external AI - prompt auto-detected
docs create FILE --products X | claude -p
docs create FILE --products X | copilot -p
# Pipe from stdin
echo 'content' | docs create --products X | claude -p
Benefits:
- Cleaner syntax (no yarn --silent needed)
- No manual --print-prompt flag when piping
- Consistent with industry tools (git, npm, etc.)
- Backward compatible with yarn commands
Change log() function to use console.error instead of console.log.
This ensures that when stdout is piped (e.g., to 'code -'), only
the prompt file path is sent through the pipe, while progress
messages remain visible on the terminal via stderr.
Usage:
echo 'content' | yarn --silent docs:create --products X | code -
When running outside Claude Code, script now outputs prompt file path
to stdout by default (or prompt text with --print-prompt flag).
This enables integration with external AI tools without requiring flags.
Inside Claude Code, script continues to run Task() agent automatically.
Changes:
- Add isClaudeCode() detection function
- Add outputPromptForExternalUse() helper
- Add PROMPT_FILE constant for .tmp/scaffold-prompt.txt
- Update both URL-based and draft-based workflows
- Update help text with environment-aware behavior examples
Allows piping prompt to other AI tools or saving to file:
yarn docs:create --print-prompt draft.md > prompt.txt
yarn docs:create --print-prompt draft.md | llm -m gpt-4
The flag:
- Prepares context and selects products
- Generates the full AI prompt
- Outputs to stdout and exits
- Works with both URL-based and draft-based workflows
- stdin now requires --products flag with product keys
- removed early return in promptUser() that prevented interactive prompts
- updated help text with stdin + --products examples
- prevents 'No products selected' error when running interactively
Jason Stirnaman