[mnriem]

Description

Document the shared public authoring contracts for built-in and externally installed integrations and workflow steps on the docs site. Add an integration API reference to site navigation, expand the workflow-step reference, and distinguish shared APIs from external packaging and trust requirements.

Replace docs-site links to repository design documents with public documentation or self-contained explanations. Remove private registry wiring, execution methods, and implementation maps while retaining author-facing lifecycle and resume guarantees.

Testing

Set up this checkout's .venv and editable install using the local development guide. Run commands from the checkout root.

• Tested locally with .venv/bin/specify --help (Windows PowerShell: .\.venv\Scripts\specify.exe --help)
• Ran relevant existing tests with .venv/bin/python -m pytest tests -q (Windows PowerShell: .\.venv\Scripts\python.exe -m pytest tests -q); use affected test paths for focused checks and LC_ALL=en_US.UTF-8 on macOS
• Tested with a sample project (if applicable)

Documentation-only change; CLI, pytest, and sample-project checks were not run because no executable behavior changed.

• git diff --check — passed.
• python3 - (inline documentation validation) — passed: local link targets, API anchors, Python example syntax, site registration, documented context fields, and the step example's successful and invalid-input paths.
• DocFX build — not run; DocFX is not installed in the environment.

AI Disclosure

• I did not use AI assistance for this contribution
• I did use AI assistance (fill in the disclosure below)

AI disclosure: Authored with GitHub Copilot using GPT-6.1 Sol (model ID: gpt-6.1-sol), default session settings, autonomous editing under user direction. AI assistance covered repository inspection, documentation authoring, automated documentation checks, commit preparation, and PR creation. No runtime source code was changed.

[Copilot]

🟡 Changes recommended

Two moderate documentation inaccuracies could mislead integration authors about CLI flags and the base skills post-processing behavior.

2 open issues

• Distinguish command post-processing from skills post-processing · New
• Clarify CLI dispatch differences across integration bases · New

What changed in this PR

This documentation-only pull request publishes public authoring contracts for integrations and workflow steps, replacing private implementation details and internal design-document references with supported API, packaging, lifecycle, and trust guidance.

Changes:

• Adds integration and workflow-step API references covering authoring, packaging, dispatch, context, lifecycle, resume, ownership, and trust.
• Removes private registry, execution, and implementation-map details from public documentation.
• Updates navigation, cross-references, contributor guidance, and overview pages.

File	Summary	Review findings
docs/​workflows/​api.md	Simplifies persistence and resume documentation around public lifecycle guarantees.	—
docs/​workflow-steps/​overview.md	Renames the workflow-step API navigation entry.	—
docs/​workflow-steps/​developing.md	Links custom-step authors to the public API and clarifies thread-safety guidance.	—
docs/​workflow-steps/​cli.md	Updates the API reference link.	—
docs/​workflow-steps/​api.md	Documents the public step contract, context fields, results, failures, discovery, and resume behavior.	Moderate (1 vote): Clarify that PENDING and RUNNING are not lifecycle controls, since returning either status completes the occurrence.
docs/​toc.yml	Adds the integration API reference to site navigation.	—
docs/​README.md	Adds the integration API reference to the documentation index.	—
docs/​presets/​api.md	Removes the private implementation map and retains public script-resolution guidance.	—
docs/​overview/​core.md	Replaces an internal FileHelper design link with a self-contained explanation.	—
docs/​integrations/​index.md	Links the integration directory to the new API reference.	—
docs/​integrations/​contributing.md	Directs contributors to public integration contracts and lifecycle requirements.	—
docs/​integrations/​cli.md	Replaces internal design links with public API, ownership, and lifecycle references.	—
docs/​integrations/​catalog.md	Links catalog authors to the public integration API.	—
docs/​integrations/​api.md	Adds the public integration adapter, packaging, dispatch, ownership, trust, and lifecycle reference.	Moderate (3 votes): Distinguish per-format CLI defaults because TOML emits -m rather than --model, while YAML performs no CLI dispatch. Moderate (2 votes): Clarify that the base skills post-processor injects shared hook guidance rather than passing content through unchanged.
docs/​how-to/​local-development.md	Updates the integration development reference.	—
docs/​guides/​agentic-sdlc.md	Distinguishes internal design documents from public authoring contracts.	—

_{Review effort: Lite (auto)}

[mnriem]

Addressed the review in 199d048: the integration reference now distinguishes the per-base CLI flags and lack of default YAML dispatch, explains that the base skills post-processor injects shared hook-invocation guidance, and clarifies that returning PENDING or RUNNING does not keep a workflow-step occurrence active. The documentation was checked against the source methods, including dispatch, post-processing, and returned-status behavior. Posted on behalf of @mnriem with GitHub Copilot (GPT-6.1 Sol, default session settings, autonomous documentation editing and validation).

[Copilot]

🔵 Needs a closer look

The documentation misstates command-hook coverage, promises a frontmatter name that is only conditionally injected, and incorrectly describes ordinary integration listing as import-free.

No open issues 🎉

3 previously missed issues

In code that hasn't changed since last review

Clarify that frontmatter name injection is conditional

docs/​integrations/​api.md:168

The command name is not guaranteed in the hook's frontmatter: agents.py:799–802 injects it only when registrar_config.inject_name is enabled. For templates without a name, an adapter relying on this guarantee and reading frontmatter["name"] will raise KeyError. Document the conditional injection rather than promising the field unconditionally.

Document inherited setup hooks' limited command-processing scope

docs/​integrations/​api.md:176

Inherited Markdown, TOML, and YAML setup() methods install core templates without calling process_registered_command() or post_process_command_content(). Relying only on these hooks can therefore leave core commands without required agent-specific transformations. Document their command-registration scope and the need for custom, tracked setup transformations; inherited skills setup already calls its skills post-processor.

Distinguish metadata-only catalog listing from adapter-loading list

docs/​integrations/​api.md:269

Ordinary specify integration list loads trusted installed adapter code; only list --catalog is metadata-only. Describing all listing as import-free could cause someone inspecting an adapter to execute its code unexpectedly. Name the metadata-only commands explicitly and distinguish ordinary integration list.

2 resolved since last review

• Clarify CLI dispatch differences across integration bases
• Distinguish command post-processing from skills post-processing

_{Review effort: Balanced (auto)}

[Copilot]

🔵 Needs a closer look

The documentation presents the hook as universal, but native /SKILL.md registration and fresh extension installs can bypass post-processing, leaving contributed skills unchanged.

No open issues 🎉

1 previously missed issue

In code that hasn't changed since last review

Clarify native skill registration bypasses post-processing

docs/​integrations/​api.md:175

The native /SKILL.md registration path does not call post_process_skill_content() (src/specify_cli/agents.py:400–443), and a fresh extension install skips the later skill generator when the file already exists (src/specify_cli/extensions/__init__.py:1635–1645). An adapter following this advice can therefore transform core skills but leave contributed skills unchanged. Document this limitation rather than presenting the hook as a universal skills equivalent of command post-processing.

_{Review effort: Balanced (auto)}

[mnriem]

Addressed the recent documentation reviews in ebce4a2 and 863f890. The reference now makes frontmatter name injection conditional, separates command-registration hooks from inherited core setup, distinguishes metadata-only catalog inspection from adapter-loading integration list, and documents that the skills post-processor is not called by every Spec Kit generation path. Here the affected skills are SKILL.md files generated by Spec Kit from extension or preset commands, not unrelated agent- or user-supplied skills. Existing targeted skill coverage passed (291 tests); the earlier Windows timeouts did not recur on ebce4a2, whose full test and lint checks passed. Fresh checks are being run for 863f890. Posted on behalf of @mnriem with GitHub Copilot (GPT-6.1 Sol, default session settings, autonomous documentation editing and validation).

[Copilot]

🟡 Changes recommended

The documentation incorrectly states that the hook is skipped for contributed skills, while the cited extension and preset paths do invoke it; it should instead describe only the existing-file limitation.

1 open issue

• Clarify when skill-generation hooks run · New

_{Review effort: Lite (auto)}

[mnriem]

Updated the skill-hook reference in 8f2dd2a to name inherited core setup and extension/preset skill generation as hook callers. The caveat now concerns only files skipped by a later generation pass, including files created by earlier command registration, rather than suggesting that contributed-skill generators omit the hook. This is a documentation correction, not a change to runtime hook wiring. Existing targeted skill coverage passed (291 tests). Posted on behalf of @mnriem with GitHub Copilot (GPT-6.1 Sol, default session settings, autonomous documentation editing and validation).

[Copilot]

🔵 Needs a closer look

The broad public API documentation change affects integration lifecycle, dispatch, and workflow-resume semantics, while the unrun DocFX build leaves navigation, rendering, and anchor behavior for maintainer verification.

No open issues 🎉

1 resolved since last review

• Clarify when skill-generation hooks run

_{Review effort: Lite (auto)}

[mnriem]

For clarity, this PR documents existing integration lifecycle, dispatch, and workflow-resume behavior; it does not change those contracts or their implementations. All 16 changed files are under docs/, with no changes to executable source, templates, scripts, or CI configuration. I rechecked the descriptions against the current integration base/installer and workflow base/execution sources, and 894 existing targeted contract and resume tests passed. The DocFX validation gap is now closed: DocFX 2.81.0 built the site with zero errors and two warnings about pre-existing ../ glob entries in the unchanged docfx.json. The generated API pages, navigation entry, and referenced section anchors were also checked. All current PR checks pass at 8f2dd2a. Posted on behalf of @mnriem with GitHub Copilot (GPT-6.1 Sol, default session settings, autonomous source comparison and validation; no additional repository changes).

[Copilot]

🟢 Approval recommended

No active review issues are recorded for the documentation changes clarifying public integration and workflow-step authoring contracts.

No open issues 🎉

_{Review effort: Balanced (auto)}