docs: establish spec governance and restructure 28 specs

[joshsmithxrm]

Summary

• Session 1: Established spec governance infrastructure — Constitution Spec Laws (SL1-SL5), updated template (Surfaces, Changelog, no Version), migrated 6 skills from README index to frontmatter grep, auto-generated README via scripts/generate-spec-readme.py, added /spec reconcile mode
• Session 2: Restructured all 28 domain specs per the governance triage table — decomposed panel-parity.md into 5 feature specs, merged 5 TUI surface specs into domain specs, consolidated query/data-explorer/solutions specs, renamed vscode-webview-cdp-tool.md, moved 2 project specs to docs/plans/
• Net result: 33 specs → 31 files (28 domain specs + 3 special). All specs have Surfaces frontmatter, Changelog sections, grep-friendly Code paths, and no Version lines.

Test Plan

• Verify scripts/generate-spec-readme.py produces correct README from frontmatter
• Verify all 28 domain specs have compliant frontmatter (Surfaces, Code, no Version)
• Verify all cross-references point to existing files (no broken links)
• Verify all 17 spec-governance ACs pass

Verification

• /gates passed (docs-only — no code gates applicable)
• /verify completed (surfaces: CLI — README generator script)
• /qa completed (surfaces: CLI)
• /review completed (findings: 5 — 3 important fixed, 2 suggestions)

🤖 Generated with Claude Code

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly refines the documentation and specification management within the project. It introduces a robust governance model for specifications, ensuring that documentation remains accurate and consistent with the codebase. By centralizing spec discovery and enabling automated reconciliation, it streamlines the development workflow and enhances clarity for all contributors.

Highlights

• Spec Governance Infrastructure Established: Implemented a new spec governance framework, including the addition of Spec Laws (SL1-SL5) to the Constitution, an updated spec template with 'Surfaces' frontmatter and a 'Changelog' section, and the introduction of an auto-generated specs/README.md to ensure consistency and prevent drift.
• Spec Discovery Mechanism Modernized: Migrated all relevant skills (/spec, /spec-audit, /gates, /review, /implement, ext-panels) from relying on specs/README.md for spec discovery to directly grepping spec frontmatter for **Code:** lines, removing hardcoded mappings and improving accuracy.
• Enhanced /spec Command with Reconcile Mode: The /spec command now includes a 'reconcile' mode that compares spec content against code, identifies missing or stale Acceptance Criteria (ACs), performs member-count verification, and proposes changes to align the spec with the current implementation.
• Comprehensive Spec Restructuring: Restructured 28 existing domain specifications by decomposing panel-parity.md into five new feature specs, merging five TUI surface specs into their respective domain specs, consolidating query and data explorer specifications, renaming vscode-webview-cdp-tool.md, and moving two project specs to docs/plans/.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a comprehensive and well-thought-out governance model for the project's specifications. The changes are extensive, including amending the constitution with 'Spec Laws', updating the spec template, and decoupling agent skills from a static README by introducing a dynamic, grep-based discovery mechanism. A new Python script to auto-generate the specs/README.md is a great addition for ensuring documentation stays synchronized. The restructuring of 28 specs, separating project plans from living domain documents and consolidating surface-specific details, significantly improves the organization and maintainability of the documentation. Overall, this is an excellent set of changes that will improve the quality and consistency of the project's specifications. I have one minor suggestion to improve the robustness of the new README generation script.