Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

[awf-feature-surfacing] Surface model-routing and governance toolset guidance

Open Beginner friendly
  • Is something wrong?
#68,542 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
68/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Tech stack
github-actions
Domain
documentation

Research direction

Start with the stale wording at line 97 of .github/aw/syntax-engine.md, and check it against docs/src/content/docs/reference/model-routing.md, which already states the correct rules. Then add governance to the Available list at line 22 of docs/src/content/docs/reference/github-tools.md, using pkg/workflow/data/github_toolsets_permissions.json for the tool purposes and token permissions. Done when both pages match the schema and that permission map.

Written by the indexing model from the issue text.

Description

automation awf compiler specifications
Overview

The seven-day AWF spec/compiler review found two user-facing guidance gaps in recently changed capabilities. The compiler and schema accept the behavior, but two discoverable syntax references still give incomplete or incorrect instructions.

Key findings
  • P2 — Model routing syntax: .github/aw/syntax-engine.md says engine.model-routing.allowed-models is required and implies it limits models the routed task may call. Since #68495, it is an optional router candidate list (AWF v0.28.33+); only models.allowed and models.blocked set the request policy. The same syntax entry omits the engine.model-provider: github requirement for routed Claude and Codex workflows enforced by #68080.
  • P2 — GitHub governance toolset: The tools.github.toolsets schema accepts governance after #67738, and .github/aw/syntax-tools-imports.md lists it, but the Available list in docs/src/content/docs/reference/github-tools.md omits it. The reference also lacks a short explanation of its custom property and ruleset tools and token permissions.
Evidence and current surfacing
  • pkg/parser/schemas/main_workflow_schema.json has engine.model-routing required fields goal and mode only, and describes allowed-models as optional router candidates. It includes governance in github_toolset_name.
  • pkg/workflow/model_routing.go applies routing policy and provider validation; pkg/workflow/data/github_toolsets_permissions.json maps governance to custom property and ruleset tools and their permission needs.
  • docs/src/content/docs/reference/model-routing.md correctly explains optional candidates, the AWF version boundary, request policy, and the GitHub provider requirement. docs/src/content/docs/reference/frontmatter.md also describes the candidate/policy distinction.
  • .github/aw/syntax-engine.md:97 retains the stale required-field and request-limit wording. docs/src/content/docs/reference/github-tools.md:22 has the incomplete toolset list.
  • Relevant changes: #68495 (63e2c65) and #68080 (70f8448) for routing; #67738 for GitHub MCP toolsets.
Next actions
  • P2: Update .github/aw/syntax-engine.md to call allowed-models optional for AWF v0.28.33+, describe it as router candidates only, and point readers to models.allowed / models.blocked for request policy. State that routed Claude and Codex must resolve engine.model-provider to github.
  • P2: Update the GitHub tools reference's available-toolsets list and add a compact governance example with the tool purposes and required token permissions, using the permission map as the source.

Generated by 🧭 Daily AWF Spec Compiler Surfacing Review · codex · gpt60 · 127.8 AIC · ⌖ 5.96 AIC · ⊞ 14.1K · ◷

  • expires on Oct 20, 2026, 2:27 PM UTC-08:00
Dominant language
Go
Stars
5.4k
Forks
576
Avg merge
7h 21m
Merged PRs (30d)
816

Getting set up

Open in Codespaces

Starts the project's dev container in your browser, under your own GitHub account.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from github/gh-aw

All issues in github/gh-aw

Similar issues

More Go issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.