diff --git a/docs/src/content/docs/patterns/spec-ops.md b/docs/src/content/docs/patterns/spec-ops.md index c7bb293aee..366d17a1f6 100644 --- a/docs/src/content/docs/patterns/spec-ops.md +++ b/docs/src/content/docs/patterns/spec-ops.md @@ -3,28 +3,14 @@ title: SpecOps description: Maintain and propagate W3C-style specifications using agentic workflows --- -SpecOps is a pattern for maintaining formal specifications using agentic workflows. It leverages the [`w3c-specification-writer` agent](https://github.com/github/gh-aw/blob/main/.github/agents/w3c-specification-writer.agent.md) to create W3C-style specifications with RFC 2119 keywords (MUST, SHALL, SHOULD, MAY) and automatically propagates changes to consuming implementations. - -Use SpecOps when you need to: -- Maintain formal technical specifications -- Keep specifications synchronized across multiple repositories -- Ensure implementations stay compliant with specification updates +SpecOps is a pattern for maintaining formal specifications using agentic workflows. It leverages the [`w3c-specification-writer` agent](https://github.com/github/gh-aw/blob/main/.github/agents/w3c-specification-writer.agent.md) to create W3C-style specifications with RFC 2119 keywords (MUST, SHALL, SHOULD, MAY) and automatically propagates changes to consuming implementations across repositories. ## How SpecOps Works -SpecOps coordinates specification updates across agents and repositories: - -1. **Update specification** - Trigger a workflow with the `w3c-specification-writer` agent to modify the specification document with RFC 2119 keywords, version numbers, and change log entries. - -2. **Review changes** - Review and approve the specification changes in the pull request. - -3. **Propagate automatically** - When merged to main, agentic workflows detect the updates and analyze impact on consuming repositories. - -4. **Update implementations** - Coding agents create pull requests to update implementations in consuming repositories (like [gh-aw-mcpg](https://github.com/github/gh-aw-mcpg)) to comply with new requirements. - -5. **Verify compliance** - Test generation workflows update compliance test suites to verify implementations satisfy the new specification requirements. - -This automated workflow ensures specifications remain the single source of truth while keeping all implementations synchronized and compliant. +1. **Update specification** — Trigger a workflow with the `w3c-specification-writer` agent to edit the spec document (RFC 2119 keywords, version bump, change log). +2. **Review changes** — Approve the specification pull request. +3. **Propagate automatically** — On merge, workflows detect updates and create PRs in consuming repositories (like [gh-aw-mcpg](https://github.com/github/gh-aw-mcpg)) to maintain compliance. +4. **Verify compliance** — Test generation workflows update compliance test suites against the new requirements. ## Update Specifications @@ -75,8 +61,6 @@ Update the MCP Gateway specification using the w3c-specification-writer agent. 4. Create a pull request with the updated specification ``` -The agent applies RFC 2119 keywords, updates semantic versioning, and creates a pull request. - ## Propagate Changes After specification updates merge, automatically propagate changes to consuming repositories: @@ -126,18 +110,11 @@ The MCP Gateway specification has been updated. Propagate changes to consuming r 4. Create tracking issue linking all PRs ``` -This workflow automatically updates consuming repositories like [gh-aw-mcpg](https://github.com/github/gh-aw-mcpg) to maintain compliance. - ## Specification Structure -W3C-style specifications follow a formal structure: +W3C-style specifications require: Abstract, Status, Introduction, Conformance, numbered technical sections with RFC 2119 keywords, Compliance testing, References, and a Change log. -**Required Sections**: -- Abstract, Status, Introduction, Conformance -- Numbered technical sections with RFC 2119 keywords -- Compliance testing, References, Change log - -**Example**: +**Example RFC 2119 usage**: ```markdown ## 3. Gateway Configuration @@ -146,28 +123,18 @@ The gateway SHOULD log validation errors with field names. The gateway MAY cache validated configurations. ``` -See the [`w3c-specification-writer` agent](https://github.com/github/gh-aw/blob/main/.github/agents/w3c-specification-writer.agent.md) for complete specification template and guidelines. +See the [`w3c-specification-writer` agent](https://github.com/github/gh-aw/blob/main/.github/agents/w3c-specification-writer.agent.md) for a complete template and guidelines. ## Semantic Versioning -- **Major (X.0.0)** - Breaking changes -- **Minor (0.Y.0)** - New features, backward-compatible -- **Patch (0.0.Z)** - Bug fixes, clarifications - -## Example: MCP Gateway +| Bump | When | +|------|------| +| **Major (X.0.0)** | Breaking changes | +| **Minor (0.Y.0)** | New features, backward-compatible | +| **Patch (0.0.Z)** | Bug fixes, clarifications | -The [MCP Gateway Specification](/gh-aw/reference/mcp-gateway/) demonstrates SpecOps: - -- **Specification**: Formal W3C document with RFC 2119 keywords -- **Implementation**: [gh-aw-mcpg](https://github.com/github/gh-aw-mcpg) repository -- **Maintenance**: Automated pattern extraction via `layout-spec-maintainer` workflow +The [MCP Gateway Specification](/gh-aw/reference/mcp-gateway/) is a live example — maintained by the `layout-spec-maintainer` workflow and implemented in [gh-aw-mcpg](https://github.com/github/gh-aw-mcpg). ## Related Patterns -- **[MultiRepoOps](/gh-aw/patterns/multi-repo-ops/)** - Cross-repository coordination - -## References - -- [W3C Specification Writer Agent](https://github.com/github/gh-aw/blob/main/.github/agents/w3c-specification-writer.agent.md) - Custom agent for writing W3C-style specifications -- [MCP Gateway Specification](/gh-aw/reference/mcp-gateway/) - Example specification -- [RFC 2119: Requirement Level Keywords](https://www.ietf.org/rfc/rfc2119.txt) - Keywords for technical specifications +- **[MultiRepoOps](/gh-aw/patterns/multi-repo-ops/)** — Cross-repository coordination