Follow-up tracked from PR #63 (tag-system removal). The @docs tag was removed at the user-facing surface, but the underlying output_mode="docs" codepath is intentionally left dormant so a dedicated docs subcommand can be wired without re-implementing the engine.
What's already in place (dormant)
| Location |
What it does |
engineer.run_reverse_engineering(..., output_mode="docs") |
SDK dispatch already accepts output_mode |
base_engineer._get_existing_client_guidance |
Switches existing_label/existing_artifact between "scripts"/"docs" automatically |
cli.run_engineer(..., output_mode="client") |
Internal helper accepts output_mode, but no caller passes "docs" today |
prompts/engineer/user.md |
Template variable tag_mode_label flips to "Documentation" when docs mode is active |
What the follow-up PR needs
- New click subcommand
docs:
- Args/flags mirroring
engineer: positional run_id (optional — defaults to latest run), -p/--prompt (override), -m/--model, -o/--output-dir
- When called:
run_engineer(run_id, output_mode="docs", ...)
- Latest-run resolution:
session_manager.get_history(limit=1)[0]["run_id"] when no positional given (mirrors what the old @docs standalone tag did)
- HAR-existence guard: the old
@docs path validated that recording.har exists for the target run before running. Replicate that check in the new subcommand to keep the same error UX.
- Output directory: docs go under
get_docs_dir(run_id, output_dir) (already exists in utils.py). Make sure the new subcommand surfaces the resulting path on success.
- README: add a Docs Mode section under Usage Modes between Engineer Mode and Agent Mode.
- CHANGELOG (Unreleased): document the new
docs subcommand and reference this issue.
- Tests: a
tests/test_cli_docs_command.py mirroring the structure of test_cli_engineer_command.py — covers docs (no args → latest run), docs <run_id>, docs <run_id> -p "...", missing-HAR error.
Out of scope here
References
Follow-up tracked from PR #63 (tag-system removal). The
@docstag was removed at the user-facing surface, but the underlyingoutput_mode="docs"codepath is intentionally left dormant so a dedicateddocssubcommand can be wired without re-implementing the engine.What's already in place (dormant)
engineer.run_reverse_engineering(..., output_mode="docs")output_modebase_engineer._get_existing_client_guidanceexisting_label/existing_artifactbetween"scripts"/"docs"automaticallycli.run_engineer(..., output_mode="client")output_mode, but no caller passes"docs"todayprompts/engineer/user.mdtag_mode_labelflips to"Documentation"when docs mode is activeWhat the follow-up PR needs
docs:engineer: positionalrun_id(optional — defaults to latest run),-p/--prompt(override),-m/--model,-o/--output-dirrun_engineer(run_id, output_mode="docs", ...)session_manager.get_history(limit=1)[0]["run_id"]when no positional given (mirrors what the old@docsstandalone tag did)@docspath validated thatrecording.harexists for the target run before running. Replicate that check in the new subcommand to keep the same error UX.get_docs_dir(run_id, output_dir)(already exists inutils.py). Make sure the new subcommand surfaces the resulting path on success.docssubcommand and reference this issue.tests/test_cli_docs_command.pymirroring the structure oftest_cli_engineer_command.py— coversdocs(no args → latest run),docs <run_id>,docs <run_id> -p "...", missing-HAR error.Out of scope here
@docsREPL tag — the principle from cleanup: remove tag system, expose equivalents as CLI flags #63 is that capabilities live as first-class subcommands/flags, not inline tags.References
@docstag was retired)docs --jsonsurface for agents would be nice eventually)