Skip to content

docs(assess): clarify README invocation guidance - #5068

Open
WOLIKIMCHENG wants to merge 2 commits into
github:mainfrom
WOLIKIMCHENG:docs/assess-invocation-guidance
Open

WOLIKIMCHENG wants to merge 2 commits into
github:mainfrom
WOLIKIMCHENG:docs/assess-invocation-guidance

Conversation

@WOLIKIMCHENG

@WOLIKIMCHENG WOLIKIMCHENG commented Oct 23, 2026 •

Copy link
Copy Markdown
Contributor

Description

Use GitHub Copilot's default skills syntax throughout the assess README, including the command table, examples, and handoff references. Match the main README's invocation guidance and retain the instruction to run skills in the agent's chat, not the terminal.

Bump the assess extension to 1.0.2 and synchronize its catalog entry and bundle extension pin. The five stages and optional handoff remain unchanged.

Testing

  • 69 focused tests passed, covering extension versions, bundle consistency and update delivery, the version guard, assess installation, and bundled workflows.
  • The extension version guard passed against an isolated candidate containing this patch.
  • Checked README command references and wording; git diff --check passed.

AI Disclosure

  • I did use AI assistance (described below)

AI disclosure: AI-assisted tools were used to update the assess README and version metadata and verify the changes.

Assisted-by: OpenAI Codex (model: gpt-6.1-sol, autonomous)
@WOLIKIMCHENG
WOLIKIMCHENG requested a review from mnriem as a code owner October 23, 2026 07:58
@mnriem mnriem added the triage-nice-to-have Verdict: evidence-backed fix or greenlit feature — land after review label Oct 23, 2026
@mnriem
mnriem requested a max review from Copilot October 23, 2026 14:29

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The README edit lacks the synchronized extension version updates enforced by CI.

1 open issue
What changed in this PR

Clarifies how to invoke the assess extension across agent integrations while preserving its five-stage workflow and optional handoff.

Changes:

  • Distinguishes canonical command IDs from integration-specific syntax and links to invocation guidance.
  • Labels the example as GitHub Copilot’s default skills mode and updates it to use hyphenated skill names in agent chat.
File Description
extensions/​assess/​README.md Clarifies invocation syntax and updates the Copilot chat example.

Review effort: Max

Comment thread extensions/assess/README.md Outdated
| `speckit.assess.shape` | Shape 2–3 concept-level options with appetite and trade-offs; recommend one (or none). | `concept.md` |
| `speckit.assess.decide` | Score against criteria and render the verdict; hand `go` ideas to `/speckit.specify`. | `decision.md` |

The table lists canonical command IDs. Dotted `/speckit.*` references in this README identify commands; the invocation depends on your integration and installed mode. For example, intake is `/speckit-assess-intake` in GitHub Copilot's default skills mode, `$speckit-assess-intake` in Codex skills mode, and `/skill:speckit-assess-intake` in Kimi. Use the form exposed by your agent; see [Command invocation](https://github.github.io/spec-kit/integrations/cli.html#command-invocation) and [Copilot's commands layout](https://github.github.io/spec-kit/integrations/copilot.html#commands-layout).
@mnriem

mnriem commented Oct 23, 2026

Copy link
Copy Markdown
Collaborator

Thanks for clarifying the invocation guidance. Please align the assessment README with the main README: use GitHub Copilot’s default skills syntax throughout, including the command table, examples, and handoff references, rather than retaining dotted command IDs or listing other agents’ syntax variations.

Use the same wording as the main README:

This example uses GitHub Copilot's default skills syntax. For another agent, use its equivalent invocation syntax.

This keeps the README focused on one consistent syntax and leaves integration-specific variations in the shared reference. Please retain the clarification that skills run in the agent’s chat, not the terminal.

@mnriem mnriem added the author-awaiting Waiting on author response label Oct 23, 2026
Assisted-by: OpenAI Codex (model: gpt-6.1-sol, autonomous)
@WOLIKIMCHENG

Copy link
Copy Markdown
Contributor Author

Thanks for the guidance. Updated the assess README to use GitHub Copilot's default skills syntax throughout, retained the agent-chat guidance, and bumped the assess extension, catalog entry, and bundle pin to 1.0.2 in commit 97ec3fa07805a7d402e0fdd9a4b94e0b2eeb55f2. The 69 focused tests and isolated extension version guard passed.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

author-awaiting Waiting on author response triage-nice-to-have Verdict: evidence-backed fix or greenlit feature — land after review

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants