docs: clarify spec-driven development is mandatory for all AI agents #55

tommcd · 2025-11-25T20:24:31Z

Summary

Clarifies that this project was built using spec-driven development with Kiro specs, and ALL AI agents must understand this methodology before contributing.

Changes

AGENTS.md

Clarified that .kiro/steering/ docs are auto-included for Kiro only
Other agents (Claude, Codex, Copilot) must explicitly read steering docs
Added explicit instructions on which files to read before starting
Listed all essential steering documents with their purposes

CLAUDE.md

Emphasized spec-driven development is critical and mandatory
Established clear hierarchy: AGENTS.md → workflow.md → ai-agent-quick-reference.md
Added prominent notice that project was built with spec-driven development
Clarified CLAUDE.md is comprehensive reference, not primary guide

Why This Matters

This project was built entirely using spec-driven development. Any AI agent working on it MUST:

Understand how Kiro specs work (requirements → design → tasks)
Read the steering documents (workflow, quality standards, golden rules)
Follow the spec-driven development cycle

Without this understanding, agents will not be able to contribute effectively.

Testing

Docs build successfully: tox -e docs-build
All pre-commit hooks pass

- Emphasize that this project was built with spec-driven development - Clarify that .kiro/steering/ docs are auto-included for Kiro only - Other agents (Claude, Codex, Copilot) must explicitly read steering docs - Update AGENTS.md to instruct non-Kiro agents what to read - Update CLAUDE.md to emphasize spec-driven methodology is critical - Establish clear hierarchy: AGENTS.md → workflow.md → ai-agent-quick-reference.md - Archive old core-api-stabilization spec development artifacts Critical message: All AI agents MUST understand Kiro specs before contributing

gemini-code-assist · 2025-11-25T20:24:57Z

Summary of Changes

Hello @tommcd, 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 enhances the project's documentation to enforce and clarify the mandatory use of spec-driven development for all AI agents contributing to the codebase. It ensures that agents are properly guided through the project's methodology, reading essential steering documents in a defined order, and archives outdated spec-related files for better organization.

Highlights

Mandatory Spec-Driven Development: Explicitly states that all AI agents, not just Kiro, must understand and follow the project's spec-driven development methodology using Kiro specs.
Documentation Updates for AI Agents: AGENTS.md was updated to clarify which steering documents are automatically included for Kiro and which must be explicitly read by other AI agents (Claude, Codex, Copilot). It also provides a prioritized list of essential documents to read before starting work.
Claude-Specific Guidance Refinement: CLAUDE.md was revised to prominently feature the mandatory nature of spec-driven development, establish a clear reading hierarchy (AGENTS.md → workflow.md → ai-agent-quick-reference.md), and clarify its role as a comprehensive reference rather than a primary guide.
Archiving Old Spec Artifacts: Historical development artifacts related to the core-api-stabilization spec were moved from .kiro/specs/ to docs/archive/specs/ and organized into subdirectories based on their purpose (development, fixes, prompts, reviews, simplification, status).

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.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

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 significantly improves the project's documentation by clarifying that spec-driven development is mandatory for all AI agents. The changes in AGENTS.md and CLAUDE.md add prominent notices and clear instructions, which will greatly help in onboarding contributors. The archival of old spec artifacts is also a good housekeeping measure. I've provided a few suggestions to enhance readability and reduce redundancy in the Markdown files. Overall, this is a valuable update.

AGENTS.md

CLAUDE.md

tommcd · 2025-11-25T20:27:30Z

@codex review

Copilot

Pull request overview

This pull request clarifies that spec-driven development with Kiro specs is mandatory for all AI agents and organizes historical spec development artifacts into an archive.

Key Changes:

Emphasizes that spec-driven development is mandatory and critical for all AI agents
Clarifies that .kiro/steering/ docs are auto-included only for Kiro, not for other agents (Claude, Codex, Copilot)
Establishes clear document hierarchy: AGENTS.md → workflow.md → ai-agent-quick-reference.md
Moves historical core-api-stabilization spec development artifacts to docs/archive/specs/

Reviewed changes

Copilot reviewed 2 out of 30 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
AGENTS.md	Clarifies steering docs auto-inclusion is Kiro-only; adds explicit instructions for other agents to read steering docs; lists essential files to read before starting
CLAUDE.md	Adds prominent spec-driven development notice at top; establishes document hierarchy; clarifies CLAUDE.md is comprehensive reference, not primary guide
docs/archive/specs/core-api-stabilization/status/*.md	Archives task review documents, final status assessments, and approval records from spec development
docs/archive/specs/core-api-stabilization/simplification/*.md	Archives backward compatibility removal proposals and completion records
docs/archive/specs/core-api-stabilization/reviews/*.md	Archives multiple review cycles, responses, and fixes applied during spec refinement
docs/archive/specs/core-api-stabilization/prompts/*.md	Archives AI review prompts and checklists used for spec validation
docs/archive/specs/core-api-stabilization/fixes/*.md	Archives documentation of all fixes applied during spec development
docs/archive/specs/core-api-stabilization/development/*.md	Archives task updates, feedback application, and design changes during development

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review for a chance to win a $100 gift card. Take the survey.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

CLAUDE.md

- Added [PLANNED] markers and backticks to Document.to_json/from_json references - Added [PLANNED] markers and backticks to Diagnostic.context_lines references - Fixes spec validation test failures in CI - Backticks prevent regex pattern matching in test validation

- Use sequential numbering (1., 2., 3.) in AGENTS.md and CLAUDE.md lists - Fix contradiction about auto-included docs in CLAUDE.md - Remove redundant 'Document Purpose' section from CLAUDE.md - Clarify that Claude must explicitly read steering docs (not auto-included)

- Added detailed step-by-step PR workflow (Steps 1-7) - Included explicit gh commands for fetching and replying to review comments - Emphasized staying on feature branch until merge is confirmed - Added 'Common PR Workflow Mistakes to Avoid' section - Updated 'Starting a New Feature' and 'Fixing a Bug' workflows - Clarified that human must confirm merge before switching to master

gemini-code-assist bot reviewed Nov 25, 2025

View reviewed changes

AGENTS.md Show resolved Hide resolved

CLAUDE.md Show resolved Hide resolved

CLAUDE.md Outdated Show resolved Hide resolved

tommcd requested a review from Copilot November 25, 2025 20:27

Copilot started reviewing on behalf of tommcd November 25, 2025 20:27 View session

Copilot finished reviewing on behalf of tommcd November 25, 2025 20:28

Copilot AI reviewed Nov 25, 2025

View reviewed changes

chatgpt-codex-connector bot reviewed Nov 25, 2025

View reviewed changes

CLAUDE.md Outdated Show resolved Hide resolved

tommcd added 3 commits November 25, 2025 20:39

tommcd merged commit 05b437e into master Nov 25, 2025
3 checks passed

tommcd deleted the feature/clarify-spec-driven-development branch November 25, 2025 20:59

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

docs: clarify spec-driven development is mandatory for all AI agents #55

docs: clarify spec-driven development is mandatory for all AI agents #55

Uh oh!

tommcd commented Nov 25, 2025

Uh oh!

gemini-code-assist bot commented Nov 25, 2025

Uh oh!

gemini-code-assist bot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tommcd commented Nov 25, 2025

Uh oh!

Copilot AI left a comment

Uh oh!

chatgpt-codex-connector bot left a comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

docs: clarify spec-driven development is mandatory for all AI agents #55

docs: clarify spec-driven development is mandatory for all AI agents #55

Uh oh!

Conversation

tommcd commented Nov 25, 2025

Summary

Changes

AGENTS.md

CLAUDE.md

Archive

Why This Matters

Testing

Uh oh!

gemini-code-assist bot commented Nov 25, 2025

Summary of Changes

Highlights

Footnotes

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tommcd commented Nov 25, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants