Update OpenSpec agent instructions for clarity and completeness #50
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
- Create proposal for streamlining agent instructions - Document three-stage workflow clearly - Update CLI command documentation - Add best practices for AI agents - Include spec deltas for documentation requirements
- Documentation updates are tooling/infrastructure changes - No specs needed for OpenSpec's own instructions - Will use --skip-specs flag when archiving
- Add decision clarity improvements (decision trees, remove ambiguity) - Include agent-specific sections (tool selection, error recovery, context management) - Restructure with clear information hierarchy - Add comprehensive implementation tasks (6 sections, 26 tasks) - Update design with industry best practices rationale Based on analysis of Claude Code, Cursor, and other coding agent patterns
- Document all 9 primary OpenSpec commands with examples - Add openspec list and list --specs prominently - Add "Before Creating Specs" rule to check existing specs first - Document all CLI flags (--json, --type, --skip-specs, etc.) - Update tasks to include 9 CLI documentation items - Add spec discovery workflow to prevent duplicate capabilities This ensures AI agents have complete CLI knowledge and avoid spec fragmentation
- Add detailed implementation steps: read docs → implement → mark complete - Emphasize reading proposal.md, design.md, and tasks.md first - Require immediate task completion marking (no batching) - Add rationale: prevents jumping straight to code without context - Update tasks to include implementation workflow documentation This ensures agents understand and follow the complete change properly
Based on OPENSPEC_COMPREHENSIVE_RETROSPECTIVE.md analysis: Added critical missing documentation: - Scenario formatting requirements (#### Scenario: headers) - #1 pain point - Complete spec file structure examples with ADDED/MODIFIED sections - Delta file location and extraction explanation - Debugging commands (show --json --deltas-only) - Troubleshooting section with common errors and solutions Expanded implementation: - Added 2 new task sections (Spec File Documentation, Troubleshooting) - Increased from 41 to 52 total implementation tasks - Added critical items to CLAUDE.md template tasks This directly addresses the retrospective's top issues: 1. Scenario format documentation (marked "COMPLETELY MISSING") 2. Complete spec file examples 3. Delta detection debugging 4. Silent parsing failure explanations
drvova
pushed a commit
to drvova/VovaSpec
that referenced
this pull request
Oct 13, 2025
…t-instructions Update OpenSpec agent instructions for clarity and completeness
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
What Changes
This PR updates the OpenSpec agent instructions to follow best practices for AI coding assistants and addresses all critical issues identified in the comprehensive retrospective.
Key Improvements:
Critical Additions (from Retrospective):
#### Scenario:headers) - was "COMPLETELY MISSING"Implementation Scope:
Test plan
openspec/changes/update-agent-instructions/openspec validate update-agent-instructionsImpact
This is a documentation-only change that will significantly improve the developer experience when using OpenSpec, particularly for AI coding assistants.
🤖 Generated with Claude Code