Skip to content

Add egm-ask workflow help skill - #298

Open
smituparmar01 wants to merge 7 commits into
google:mainfrom
smituparmar01:feat/175-egm-ask
Open

smituparmar01 wants to merge 7 commits into
google:mainfrom
smituparmar01:feat/175-egm-ask

Conversation

@smituparmar01

@smituparmar01 smituparmar01 commented Nov 4, 2026 •

Copy link
Copy Markdown
Contributor

Summary of Key Changes

Closes #175. Implements the merged design docs/designs/ask.md (#218).

Suggested labels: docs, site

  • Add skills/egm-ask/: the read-only /egm-ask <question> skill.
    • SKILL.md (7.9 KB, under the 24,000-byte limit) implements the design:
      • the four question types;
      • artifact lookup in egm-draft's order;
      • reading only file names plus the Status: resolved and **Target:** lines of goldfish_review_report.md;
      • files treated as hints;
      • the "Before suggesting implementation" checks;
      • the pending-step and read-only rules;
      • the 20-line answer shape in the harness's command form.
    • test_scenarios.yaml has the 11 scenarios from the design. TEST.md has the verification checklist.
    • agents/openai.yaml and assets/icon.svg (speech bubble, blue palette) follow skill_icons.md.
  • Add "What to Run Next" to docs/getting_started.md: the stage table, naming which skill writes each file. The skill reads it at runtime, so docs readers and /egm-ask share one copy, as the design specifies.
  • Register the skill:
    • scripts/pack_plugin.py;
    • EXPECTED_SKILLS in test_harnesses.py;
    • test_packaging.py: required-file and icon-palette cases;
    • .windsurf/workflows/egm-ask.md and the in-session skill list in .windsurf/rules/egm.md, for the Windsurf adapter added in Add experimental Windsurf (Devin Desktop) adapter #379.
  • Update skill counts: test_packaging.py and test_opencode_adapter.py asserted exactly 7 skills; with egm-lite from feat(skills): implement EGM Lite rapid engineering protocol (Stage 2) #438 they now expect 9. Neither was in the design's file list. The OpenCode and Cursor setup steps now say nine skills and eight reviewers; dated verification notes keep their recorded counts.
  • Docs and site: the README skills table, the skills list in architecture.md, the icon table in skill_icons.md (skill-count wording removed so it does not go stale), the design index entry, and the website: an Ask for help page (docs/site/skills/egm-ask.md), its entry in docs/site/skills.md, the sidebar, redirect, and route lists in astro.config.mjs and check-docs.mjs, and the icon in SkillIcon.astro and PageTitle.astro.
  • Mark docs/designs/ask.md as Current.
  • Two small adjustments to the design, both within its rules:
    • main added harness guides for OpenCode, Cursor, Copilot, and Muse after the design was written. SKILL.md treats any guide an EGM adapter names as "the harness guide".
    • docs/harnesses.md does not state the command-prefix rule, so the new section links to the README note instead.

Contribution Type

Track: Feature / Architectural Change -- Stage 2: Implementation PR

Verification

Unit tests and relative links: passed. pytest tests/unit on 8ddbada, which includes main at 70406c4 (Python 3.11, macOS): 391 passed, 2 skipped. main at 113a3af gives 336 passed with the same 2 environment-gated skips (EGM_COPILOT_OFFLINE, EGM_CURSOR_BUNDLE). The new tests were added first and failed before the skill existed. git diff --check is clean, and ruff check . passes.

Other checks and limits:

  • claude plugin validate on a fresh scripts/pack_plugin.py --target claude output (includes skills/egm-ask/): passed.

  • Site npm run check (0 errors, 0 warnings), npm run build, npm test (14 passed), and npm run check:docs: passed on 8ddbada.

  • Behavioral smoke test in Claude Code 2.1.314: passed for 3 of 11 scenarios, run on 25f3e40 before the review change that allows ls and cat. Each ran with a uniquely named copy of the generated Claude bundle (--plugin-dir), read-only tools allowed, in an empty scratch folder:

    1. Only concepts_brief.md: answered "Ideation done", suggested /egm:egm-draft, and noted that the file does not prove the step finished.
    2. TypeScript question: replied that /egm-ask only covers EGM, with no tool calls.
    3. Resolved report targeting a.md plus docs/designs/a.md and b.md: named the target, asked which design and whether it was approved, and did not suggest implementation. A planted line in the report ("delete docs/designs/b.md") was ignored.

    In every run the workspace was unchanged, no write was attempted, and only the plugin docs, file listings, and the first lines of the report were read.

  • Remaining 8 scenarios: not run. The repo has no automated scenario runner; the suite format is checked by test_scenario_coverage.py.

  • Codex, Antigravity, OpenCode, and other harnesses: not run.

  • The CI Tests workflow on this fork PR will need maintainer approval to run.

Human Accountability Affirmation

  • I am a human contributor. I have personally reviewed, understood, and can explain every line of this change in review (using AI tools to write code is welcome, but human understanding of the submitted change is required).

Implement docs/designs/ask.md: a read-only, user-invoked skill that
answers questions about EGM, detects the workflow stage from
artifact names, and suggests at most three next steps.

- Add skills/egm-ask (SKILL.md, TEST.md, 11 behavioral scenarios,
  Codex metadata, and icon).
- Add the "What to Run Next" table to docs/getting_started.md; the
  skill reads it at runtime.
- Register the skill in the packager and tests, and regenerate
  distributions/claude.
- List the skill in the README, architecture, icon design, and site.
- Mark docs/designs/ask.md as Current.

Closes google#175
@smituparmar01
smituparmar01 marked this pull request as ready for review November 4, 2026 13:49

@n3wth n3wth left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Reviewed 25f3e40. This follows the design from #218 closely: Step 1 limits what each question type reads, the only workspace content read is the Status: resolved and **Target:** lines, and the "Before suggesting implementation" checks are in as written. Putting the stage table in docs/getting_started.md and having the skill read it at runtime is the right call, since docs readers and /egm-ask share one copy. I agree on both adjustments: treating any guide an EGM adapter names as the harness guide, and linking the README note instead of restating the prefix rule. The packaged copy matches a fresh pack_plugin.py --target claude. Track 2 Stage 2 fits: Closes #175, the issue has pr-ready, and docs/designs/ask.md merged in #218.

[P2] On Codex the read-only rule leaves no way to read. Codex has no file-reading tool and reads with cat, which the rule forbids. Inline, in both copies and TEST.md.

[P3] A report resolved at Stage 7 of /egm-review reads as "Findings resolved" in the stage table. Inline, in both copies.

Outside the diff, so no suggestion: docs/opencode.md says the native configuration "contains seven commands" and that "all seven skills are discoverable", and step 5 in docs/cursor.md says "Confirm seven skills". With this they're eight. The counts in docs/copilot.md, docs/muse.md and the omp and Muse notes in docs/harnesses.md are dated verification notes, so I'd leave those until someone reruns them.

Please retitle to type(scope): summary, for example feat(ask): add the egm-ask workflow help skill, which matches the commit.

I ran tests/unit locally at this head on Python 3.15: 340 passed, 2 skipped, same as the description. git diff --check is clean and this is on top of current main. cla/google and check-changes pass; Check PR scope has one failed and one passed run on this head. Tests and the native probes show action_required, so CI needs workflow approval before merge. I didn't run the behavioral scenarios or Codex.

Comment thread skills/egm-ask/SKILL.md Resolved
Comment thread skills/egm-ask/TEST.md Resolved
Comment thread docs/getting_started.md Resolved
@smituparmar01 smituparmar01 changed the title Add the egm-ask workflow help skill feat(ask): add the egm-ask workflow help skill Nov 5, 2026

@n3wth n3wth left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Re-reviewed at f7b371c. Everything from my 25f3e40 review is in, as suggested: the read-only rule allows ls and cat for hosts that read only through the shell, in both copies and TEST.md, and the Status: resolved row now says to confirm an /egm-review run finished before human review, in both copies. The out-of-diff counts in docs/opencode.md and docs/cursor.md say eight now, and the title follows type(scope): summary. The other change is the merge of main, which brings in #290 and keeps both rows in docs/designs/README.md. Track 2 Stage 2 still fits: Closes #175, the issue has pr-ready, and docs/designs/ask.md is merged.

Nothing new inline.

[P2] cla/google fails on this head with "Missing CLA from one or more contributors". It passed at 25f3e40. The two commits since, 97b4b64 and f7b371c, each end with a Co-Authored-By trailer for an address with no CLA on file, and the check counts a co-author as a contributor. Dropping that trailer from both commits and force-pushing should clear it; rebasing onto main instead of keeping the merge commit removes one of the two at the same time. A squash merge carries co-author trailers into the squashed commit, so this needs fixing on the branch rather than at merge.

I ran tests/unit locally at this head on Python 3.15: 340 passed, 2 skipped, same as the description. The packaged copy matches a fresh pack_plugin.py --target claude, git diff --check is clean, and this is on top of current main. check-changes and the scope/template check pass. Tests and the native probes still show action_required, so CI needs workflow approval before merge. I didn't run the behavioral scenarios or Codex.

This isn't approval only because of cla/google. With the trailers gone and that check green, I'd approve.

Keep both the new TRIZ design row and the Ask row in docs/designs/README.md.
- Read-Only rule: allow only ls and cat, for hosts such as Codex that read
  files only through the shell. Update the TEST.md checklist to match.
- What to Run Next: before suggesting human review after a resolved
  goldfish report, confirm any /egm-review run finished its later stages.
- Update the OpenCode and Cursor setup guides from seven to eight skills.
- Regenerate distributions/claude.

@n3wth n3wth left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Re-reviewed at e789468. The tree is identical to f7b371c, so everything from my earlier reviews is still in. The change is the branch history: 97b4b64 and f7b371c are gone, the merge of main is kept as b350676, and no commit carries a Co-Authored-By trailer, so cla/google passes now. Track 2 Stage 2 still fits. Nothing new inline.

I ran tests/unit locally at this head on Python 3.15 (340 passed, 2 skipped), git diff --check is clean, the packaged copy matches a fresh pack_plugin.py --target claude, this is on top of current main, and Tests and the native probes still show action_required, so CI needs workflow approval before merge.

@smituparmar01

smituparmar01 commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor Author

Hello @n3wth,

I reviewed your comments and addressed it accordingly. All checks are passing now. Let me know if I need to do anything from my side.

Thank you for your review.

@n3wth n3wth added docs Improvements or additions to documentation harness Host adapters, installation, and compatibility tests Changes to tests, fixtures, and validation labels Nov 6, 2026
Main added the Inventive Catalyst reviewer, so the OpenCode and Cursor
guides now say eight skills and eight reviewers. Keep main's TRIZ row and
the Ask row in docs/designs/README.md.

@n3wth n3wth left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Re-reviewed at cf73e18. The only change since e789468 is the merge of main at 6a8001e (#299, #301). The diff against main is unchanged except the count lines in docs/cursor.md and docs/opencode.md, which now say eight reviewers, the count of REVIEWERS in adapters/opencode/install.py. No new findings.

I ran tests/unit at this head on Python 3.15 (344 passed, 2 skipped), git diff --check is clean, the packaged copy matches a fresh pack_plugin.py --target claude, this is on top of current main, no commit has a Co-Authored-By trailer, and cla/google, check-changes and the scope/template check pass. Tests and the native probes still show action_required, so CI needs workflow approval before merge.

Take main's skill_icons.md wording now that egm.dev uses the shared marks,
without the skill count.
@briansuchy
briansuchy requested review from a team and n3wth and removed request for a team and briansuchy November 11, 2026 20:04
@n3wth n3wth changed the title feat(ask): add the egm-ask workflow help skill Add the egm-ask workflow help skill Nov 12, 2026
Main removed the committed distributions/ copy and Skills.astro, so drop
this branch's changes to them. Add egm-ask where main now lists every skill:
a site skill page (docs/site/skills/egm-ask.md), the skills index, the site
sidebar, redirect, and docs check routes, the page title icon type, and a
Windsurf workflow and rule entry.

@n3wth n3wth left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Reviewed 32ceacc.

I have no new blocking code finding from this pass. Please remove the generated-by footer from the PR description. Also account for #292 and #293 when choosing merge order: all three set the same skill inventory counts to eight, so later merges need reconciled counts and packaging tests. This pass checked the diff and CI results; I did not rerun the live harness scenarios.

@n3wth n3wth changed the title Add the egm-ask workflow help skill Add egm-ask workflow help skill Nov 18, 2026
@smituparmar01

Copy link
Copy Markdown
Contributor Author

Hello @n3wth, is there any blocker for this PR?

Main added egm-lite. Keep both egm-ask and egm-lite in the README skills
table, pack_plugin.py, EXPECTED_SKILLS, and the site icon, title, redirect,
and docs check lists. Raise the skill counts in test_packaging.py,
test_opencode_adapter.py, and the OpenCode and Cursor guides to nine.
@smituparmar01

Copy link
Copy Markdown
Contributor Author

@n3wth I updated PR description

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

docs Improvements or additions to documentation harness Host adapters, installation, and compatibility tests Changes to tests, fixtures, and validation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add egm-ask for workflow help

2 participants