feat(integrations): add OpenHands skills and headless dispatch

[philo-x]

Description

Adds specify init --integration openhands, installing manifest-tracked skills under .openhands/skills/speckit-<name>/SKILL.md. Slash keyword triggers activate the generated skills. Registers the integration, catalog, invocation style, init guidance, issue forms, documentation, and opt-in agent-context mapping to AGENTS.md.

Headless dispatch uses openhands --headless -t <prompt> and --json for captured JSONL output. Executable and extra-argument environment overrides are supported. OpenHands has no --model flag; model overrides raise an actionable error explaining settings and LLM_MODEL with --override-with-envs.

The isolated install directory is multi-install safe. Documentation explains that same-named .agents/skills/ skills take precedence and that headless mode approves actions automatically.

References: OpenHands skills, CLI reference, headless mode.

Test selection reasoning

Area	Validation
Integration, registry, init and invocation style	Skill generation, dispatch contracts, multi-install isolation, sh/ps/py CLI init/uninstall; live /speckit-specify pending
Catalog and issue forms	Registry and agent configuration consistency
Context defaults	Agent-context extension suite

Testing

Executed in this checkout's virtualenv after uv sync --extra test:

• .venv/bin/python -m pytest tests/integrations/test_integration_openhands.py tests/integrations/test_registry.py tests/test_agent_config_consistency.py -q: 894 passed.
• After adding the subprocess dispatch regression, .venv/bin/python -m pytest tests/integrations/test_integration_openhands.py -q: 43 passed.
• .venv/bin/python -m pytest tests/extensions/test_extension_agent_context.py -q: 30 passed, 10 skipped.
• .venv/bin/specify --help and git diff --check: passed.

Coverage includes trigger preservation/idempotence, quoted prompts, JSON/text argv, runtime overrides, rejected unsupported configuration, workspace propagation, JSONL passthrough, modified-file preservation, and initialization/uninstallation for sh/ps/py. Subprocess dispatch is mocked. The full repository suite was not run.

Manual test results

Environment: macOS / zsh.

Command	Result
specify init --integration openhands and specify integration uninstall openhands	Passed via CliRunner sample projects for sh/ps/py
/speckit-specify inside OpenHands	Not run: OpenHands is not installed on the validation host

Draft pending the live OpenHands workflow validation required by CONTRIBUTING.md. No model request was made.

AI Disclosure

Implemented, tested, and submitted on behalf of @philo-x by Codex (model: GPT-6, autonomous). Code, tests, documentation and this PR description were AI-authored from the user's assessment. Codex checked official documentation and ran the validation above. Commit 35d149d2 includes an Assisted-by: trailer.

[Copilot]

Copilot review overview

🟡 Changes recommended

The new invocation-style and agent-context mappings lack direct regression coverage.

Get a fresh assessment by requesting another Copilot review.

Review effort: Balanced
Findings: 2

Open (2)

• Add OpenHands self-seeding coverage for AGENTS.md creation · New
• Add OpenHands rows for both ai_skills flag values · New

What changed in this PR

Adds OpenHands as a skills-based integration with headless dispatch.

Changes:

• Registers OpenHands and installs manifest-tracked skills with slash triggers.
• Adds headless execution, JSONL output, and environment overrides.
• Updates documentation, context defaults, catalogs, issue forms, and tests.

File	Description
src/​specify_cli/​integrations/​openhands/​__init__.py	Implements the OpenHands integration.
src/​specify_cli/​integrations/​__init__.py	Registers OpenHands.
src/​specify_cli/​commands/​init.py	Enables skills-oriented init guidance.
src/​specify_cli/​_invocation_style.py	Adds slash-style invocation handling.
tests/​integrations/​test_integration_openhands.py	Tests installation and dispatch behavior.
tests/​test_agent_config_consistency.py	Adds OpenHands to consistency checks.
integrations/​catalog.json	Catalogs the integration.
extensions/​agent-context/​agent-context-defaults.json	Maps OpenHands to AGENTS.md.
docs/​reference/​integrations.md	Documents setup and headless usage.
.github/​ISSUE_TEMPLATE/​feature_request.yml	Adds OpenHands to feature requests.
.github/​ISSUE_TEMPLATE/​bug_report.yml	Adds OpenHands to bug reports.
.github/​ISSUE_TEMPLATE/​agent_request.yml	Lists OpenHands as supported.

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[philo-x]

Thanks for the review and triage.

I opened this PR as the first OpenHands integration for Spec Kit, with two main pieces: project-local Spec Kit skills and runtime dispatch through openhands --headless.

After reviewing the current upstream direction more closely, I found that OpenHands-CLI is now explicitly marked as no longer actively maintained, with Agent Canvas recommended as the current OpenHands experience.

The skills side of this PR is still technically valid — the current OpenHands SDK continues to support project skills, including AgentSkills-format SKILL.md files. However, merging a new Spec Kit integration would also establish openhands --headless as its runtime contract, which would mean introducing a new integration around an upstream entry point that is no longer actively maintained.

Since Spec Kit does not currently have an OpenHands integration, there is no backward-compatibility requirement forcing us to preserve that choice. I therefore think it is better to close this draft and reassess the integration against the current Agent Canvas / Agent Server architecture before introducing OpenHands support.

If that analysis identifies a clear integration gap, I can follow up with a new focused PR based on the current upstream architecture.

Thanks again for the review.