From 7c0face31b9738d940ee8a652fcb923d1b2be710 Mon Sep 17 00:00:00 2001 From: Tabish Bidiwale Date: Sun, 24 Aug 2025 13:25:23 +1000 Subject: [PATCH 1/6] feat: add change proposal to update OpenSpec agent instructions - 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 --- .../update-agent-instructions/design.md | 53 +++++++++++++++ .../update-agent-instructions/proposal.md | 30 +++++++++ .../specs/documentation/spec.md | 65 +++++++++++++++++++ .../update-agent-instructions/tasks.md | 25 +++++++ 4 files changed, 173 insertions(+) create mode 100644 openspec/changes/update-agent-instructions/design.md create mode 100644 openspec/changes/update-agent-instructions/proposal.md create mode 100644 openspec/changes/update-agent-instructions/specs/documentation/spec.md create mode 100644 openspec/changes/update-agent-instructions/tasks.md diff --git a/openspec/changes/update-agent-instructions/design.md b/openspec/changes/update-agent-instructions/design.md new file mode 100644 index 00000000..657c882b --- /dev/null +++ b/openspec/changes/update-agent-instructions/design.md @@ -0,0 +1,53 @@ +# Design: Agent Instructions Update + +## Approach + +### Instruction Brevity +- Reduce total instruction length by ~50% while maintaining all critical information +- Use imperative mood ("Create proposal" vs "You should create a proposal") +- Replace verbose explanations with concise bullet points +- Consolidate related sections to avoid repetition + +### Three-Stage Workflow Documentation +The workflow is now prominently featured as a core concept: +1. **Creating** - Proposal generation phase +2. **Implementing** - Code development phase +3. **Archiving** - Post-deployment finalization phase + +This structure helps agents understand the lifecycle and their role at each stage. + +### CLI Documentation Updates +- Focus on the unified `openspec show` command as primary interface +- Document interactive mode capabilities +- Include all current flags and options +- Remove references to deprecated noun-first commands + +### Best Practices Section +Added explicit guidance for AI agents: +- Be concise (avoid preambles) +- Be specific (use exact references) +- Start simple (minimal first implementation) +- Justify complexity (require data/metrics) + +## Trade-offs + +### What We're Removing +- Lengthy explanations of concepts that can be inferred +- Redundant examples that don't add clarity +- Verbose edge case documentation (moved to reference section) +- Deprecated command documentation + +### What We're Keeping +- All critical workflow steps +- Complete CLI command reference +- Complexity management principles +- Directory structure visualization +- Quick reference summary + +## Implementation Notes + +The CLAUDE.md template is intentionally more concise than README.md since: +- It appears in every project root +- Agents can reference the full README.md for details +- It needs to load quickly in AI context windows +- Focus is on immediate actionable guidance \ No newline at end of file diff --git a/openspec/changes/update-agent-instructions/proposal.md b/openspec/changes/update-agent-instructions/proposal.md new file mode 100644 index 00000000..4ec40e7d --- /dev/null +++ b/openspec/changes/update-agent-instructions/proposal.md @@ -0,0 +1,30 @@ +# Update OpenSpec Agent Instructions + +## Why + +The current OpenSpec agent instructions need updates to follow best practices for AI assistant instructions (brevity, clarity, removing ambiguity), ensure CLI commands are current with the actual implementation, and properly document the three-stage workflow pattern that agents should follow. + +## What Changes + +- **Streamline agent instructions** in README.md to be more concise and action-oriented +- **Update CLAUDE.md template** to include the complete workflow documentation +- **Document the 3-stage workflow clearly**: + 1. Creating a change proposal (proposal.md, spec deltas, design.md, tasks.md) + 2. Implementing a change proposal (following tasks, marking completion) + 3. Archiving the change proposal (using archive command after deployment) +- **Update CLI command documentation** to match current implementation: + - Document `openspec show` command with proper flags and interactive mode + - Document `openspec archive` command with --skip-specs flag + - Document `openspec validate` command options + - Remove references to deprecated commands +- **Add best practices section** for AI agents on being brief and avoiding ambiguity +- **Consolidate redundant sections** to reduce overall instruction length + +## Impact + +- Affected specs: None (documentation only) +- Affected code: + - `src/core/templates/claude-template.ts` - Update CLAUDE.md template +- Affected documentation: + - `openspec/README.md` - Main OpenSpec instructions + - CLAUDE.md files generated by `openspec init` command \ No newline at end of file diff --git a/openspec/changes/update-agent-instructions/specs/documentation/spec.md b/openspec/changes/update-agent-instructions/specs/documentation/spec.md new file mode 100644 index 00000000..3bdba3b5 --- /dev/null +++ b/openspec/changes/update-agent-instructions/specs/documentation/spec.md @@ -0,0 +1,65 @@ +# Documentation Spec Delta + +## MODIFIED Requirements + +### Requirement: OpenSpec Agent Instructions + +The OpenSpec README.md SHALL provide clear, concise instructions for AI coding assistants working with OpenSpec-enabled projects. + +The instructions SHALL: +- Document the three-stage workflow (create proposal, implement, archive) +- Include current CLI command references +- Provide best practices for brevity and clarity +- Be under 50% of the original length while maintaining all critical information + +#### Scenario: AI Assistant Creates Change Proposal + +GIVEN an AI assistant receives a request for a new feature +WHEN the assistant determines a change proposal is needed +THEN the assistant SHALL: + 1. Create a change directory under `openspec/changes/[descriptive-name]/` + 2. Generate proposal.md with Why, What, and Impact sections + 3. Create spec deltas showing requirements changes + 4. Add tasks.md with implementation checklist + 5. Include design.md if technical decisions are complex + +#### Scenario: AI Assistant Implements Approved Change + +GIVEN a change proposal has been approved +WHEN the AI assistant implements the change +THEN the assistant SHALL: + 1. Follow the tasks.md checklist exactly + 2. Mark each task complete as finished + 3. Ensure code matches proposed behavior + 4. Update affected tests + 5. Keep the change in the changes/ directory (not archived) + +#### Scenario: AI Assistant Archives Completed Change + +GIVEN a change has been deployed to production +WHEN the user confirms deployment is complete +THEN the AI assistant SHALL: + 1. Run `openspec archive [change-name]` command + 2. Confirm the change moves to `changes/archive/YYYY-MM-DD-[name]/` + 3. Verify specs are updated with delta changes (unless --skip-specs used) + +### Requirement: CLAUDE.md Template + +The CLAUDE.md template generated by `openspec init` SHALL provide project-specific OpenSpec instructions. + +The template SHALL include: +- OpenSpec marker comments for safe updates +- Three-stage workflow documentation +- Quick CLI reference +- Complexity management guidelines +- Best practices for AI agents + +#### Scenario: Initialize New OpenSpec Project + +GIVEN a developer runs `openspec init` in a project +WHEN the initialization completes +THEN a CLAUDE.md file SHALL be created containing: + - The three-stage workflow documentation + - Quick CLI command reference + - Complexity management principles + - Link to full README.md for detailed guidelines \ No newline at end of file diff --git a/openspec/changes/update-agent-instructions/tasks.md b/openspec/changes/update-agent-instructions/tasks.md new file mode 100644 index 00000000..01879c42 --- /dev/null +++ b/openspec/changes/update-agent-instructions/tasks.md @@ -0,0 +1,25 @@ +# Implementation Tasks + +## 1. Update OpenSpec README.md +- [ ] 1.1 Replace current README.md content with streamlined version +- [ ] 1.2 Ensure three-stage workflow is clearly documented +- [ ] 1.3 Update CLI command documentation to match current implementation +- [ ] 1.4 Add best practices section for AI agents +- [ ] 1.5 Remove redundant or verbose sections + +## 2. Update CLAUDE.md Template +- [ ] 2.1 Update `src/core/templates/claude-template.ts` with new template content +- [ ] 2.2 Include three-stage workflow documentation +- [ ] 2.3 Add quick CLI reference section +- [ ] 2.4 Ensure complexity management section is retained + +## 3. Testing and Validation +- [ ] 3.1 Run `openspec init` in a test directory to verify new CLAUDE.md generation +- [ ] 3.2 Validate that all CLI commands documented actually work +- [ ] 3.3 Run `openspec validate` to ensure no structural issues + +## 4. Documentation Review +- [ ] 4.1 Ensure all instructions are concise and action-oriented +- [ ] 4.2 Remove any ambiguous language +- [ ] 4.3 Verify file paths and examples are accurate +- [ ] 4.4 Check that the instructions are <50% of original length while retaining all critical information \ No newline at end of file From 41fc14d3600b8af603289b56f8dc001ba2fbefce Mon Sep 17 00:00:00 2001 From: Tabish Bidiwale Date: Sun, 24 Aug 2025 13:28:22 +1000 Subject: [PATCH 2/6] fix: remove spec deltas - this is a tooling change not a capability - Documentation updates are tooling/infrastructure changes - No specs needed for OpenSpec's own instructions - Will use --skip-specs flag when archiving --- .../update-agent-instructions/proposal.md | 6 +- .../specs/documentation/spec.md | 65 ------------------- 2 files changed, 4 insertions(+), 67 deletions(-) delete mode 100644 openspec/changes/update-agent-instructions/specs/documentation/spec.md diff --git a/openspec/changes/update-agent-instructions/proposal.md b/openspec/changes/update-agent-instructions/proposal.md index 4ec40e7d..ba9f0aa6 100644 --- a/openspec/changes/update-agent-instructions/proposal.md +++ b/openspec/changes/update-agent-instructions/proposal.md @@ -22,9 +22,11 @@ The current OpenSpec agent instructions need updates to follow best practices fo ## Impact -- Affected specs: None (documentation only) +- Affected specs: None (this is a tooling/documentation change) - Affected code: - `src/core/templates/claude-template.ts` - Update CLAUDE.md template - Affected documentation: - `openspec/README.md` - Main OpenSpec instructions - - CLAUDE.md files generated by `openspec init` command \ No newline at end of file + - CLAUDE.md files generated by `openspec init` command + +Note: This is a tooling/infrastructure change that doesn't require spec updates. When archiving, use `openspec archive update-agent-instructions --skip-specs`. \ No newline at end of file diff --git a/openspec/changes/update-agent-instructions/specs/documentation/spec.md b/openspec/changes/update-agent-instructions/specs/documentation/spec.md deleted file mode 100644 index 3bdba3b5..00000000 --- a/openspec/changes/update-agent-instructions/specs/documentation/spec.md +++ /dev/null @@ -1,65 +0,0 @@ -# Documentation Spec Delta - -## MODIFIED Requirements - -### Requirement: OpenSpec Agent Instructions - -The OpenSpec README.md SHALL provide clear, concise instructions for AI coding assistants working with OpenSpec-enabled projects. - -The instructions SHALL: -- Document the three-stage workflow (create proposal, implement, archive) -- Include current CLI command references -- Provide best practices for brevity and clarity -- Be under 50% of the original length while maintaining all critical information - -#### Scenario: AI Assistant Creates Change Proposal - -GIVEN an AI assistant receives a request for a new feature -WHEN the assistant determines a change proposal is needed -THEN the assistant SHALL: - 1. Create a change directory under `openspec/changes/[descriptive-name]/` - 2. Generate proposal.md with Why, What, and Impact sections - 3. Create spec deltas showing requirements changes - 4. Add tasks.md with implementation checklist - 5. Include design.md if technical decisions are complex - -#### Scenario: AI Assistant Implements Approved Change - -GIVEN a change proposal has been approved -WHEN the AI assistant implements the change -THEN the assistant SHALL: - 1. Follow the tasks.md checklist exactly - 2. Mark each task complete as finished - 3. Ensure code matches proposed behavior - 4. Update affected tests - 5. Keep the change in the changes/ directory (not archived) - -#### Scenario: AI Assistant Archives Completed Change - -GIVEN a change has been deployed to production -WHEN the user confirms deployment is complete -THEN the AI assistant SHALL: - 1. Run `openspec archive [change-name]` command - 2. Confirm the change moves to `changes/archive/YYYY-MM-DD-[name]/` - 3. Verify specs are updated with delta changes (unless --skip-specs used) - -### Requirement: CLAUDE.md Template - -The CLAUDE.md template generated by `openspec init` SHALL provide project-specific OpenSpec instructions. - -The template SHALL include: -- OpenSpec marker comments for safe updates -- Three-stage workflow documentation -- Quick CLI reference -- Complexity management guidelines -- Best practices for AI agents - -#### Scenario: Initialize New OpenSpec Project - -GIVEN a developer runs `openspec init` in a project -WHEN the initialization completes -THEN a CLAUDE.md file SHALL be created containing: - - The three-stage workflow documentation - - Quick CLI command reference - - Complexity management principles - - Link to full README.md for detailed guidelines \ No newline at end of file From 7b13a2de03820b39c0a38b190b86fd4b4d5113d0 Mon Sep 17 00:00:00 2001 From: Tabish Bidiwale Date: Sun, 24 Aug 2025 13:36:12 +1000 Subject: [PATCH 3/6] feat: enhance proposal with agent instruction best practices - 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 --- .../update-agent-instructions/design.md | 60 +++++++++++++++---- .../update-agent-instructions/proposal.md | 39 ++++++++---- .../update-agent-instructions/tasks.md | 56 ++++++++++------- 3 files changed, 114 insertions(+), 41 deletions(-) diff --git a/openspec/changes/update-agent-instructions/design.md b/openspec/changes/update-agent-instructions/design.md index 657c882b..91e6021a 100644 --- a/openspec/changes/update-agent-instructions/design.md +++ b/openspec/changes/update-agent-instructions/design.md @@ -2,11 +2,12 @@ ## Approach -### Instruction Brevity -- Reduce total instruction length by ~50% while maintaining all critical information -- Use imperative mood ("Create proposal" vs "You should create a proposal") -- Replace verbose explanations with concise bullet points -- Consolidate related sections to avoid repetition +### Information Architecture +- **Front-load critical information** - Three-stage workflow comes first +- **Clear hierarchy** - Core Workflow → Quick Start → Commands → Details → Edge Cases +- **50% length reduction** - Target ~285 lines from current ~575 lines +- **Imperative mood** - "Create proposal" vs "You should create a proposal" +- **Bullet points over paragraphs** - Scannable, concise information ### Three-Stage Workflow Documentation The workflow is now prominently featured as a core concept: @@ -22,12 +23,49 @@ This structure helps agents understand the lifecycle and their role at each stag - Include all current flags and options - Remove references to deprecated noun-first commands -### Best Practices Section -Added explicit guidance for AI agents: -- Be concise (avoid preambles) -- Be specific (use exact references) -- Start simple (minimal first implementation) -- Justify complexity (require data/metrics) +### Agent-Specific Enhancements +Based on industry best practices for coding agents (Claude Code, Cursor, etc.): + +**Decision Clarity** +- Clear decision trees eliminating ambiguous conditions +- Concrete examples for each decision branch +- Simplified bug vs feature determination + +**Tool Usage Guidance** +- Tool selection matrix (when to use Grep vs Glob vs Read) +- Error recovery patterns for common failures +- Verification workflows to confirm correctness + +**Context Management** +- "Before Any Task" checklist for gathering context +- What to read before starting any work +- How to maintain state across interactions + +**Best Practices** +- Be concise (one-line answers when appropriate) +- Be specific (file.ts:42 line references) +- Start simple (<100 lines, single-file defaults) +- Justify complexity (require metrics/data) + +## Design Rationale + +### Why These Changes Matter + +**Cognitive Load Reduction** +- Agents process instructions better with clear structure +- Front-loading critical info reduces scanning time +- Decision trees eliminate analysis paralysis + +**Industry Alignment** +- Follows patterns proven effective in Claude Code, Cursor, GitHub Copilot +- Addresses common failure modes (ambiguous decisions, missing context) +- Optimizes for LLM strengths (pattern matching) vs weaknesses (calculations) + +**Practical Impact** +- Faster agent comprehension of tasks +- Fewer misinterpretations of requirements +- More consistent implementation quality +- Better error recovery when things go wrong ## Trade-offs diff --git a/openspec/changes/update-agent-instructions/proposal.md b/openspec/changes/update-agent-instructions/proposal.md index ba9f0aa6..b41c3b0d 100644 --- a/openspec/changes/update-agent-instructions/proposal.md +++ b/openspec/changes/update-agent-instructions/proposal.md @@ -6,19 +6,38 @@ The current OpenSpec agent instructions need updates to follow best practices fo ## What Changes -- **Streamline agent instructions** in README.md to be more concise and action-oriented -- **Update CLAUDE.md template** to include the complete workflow documentation -- **Document the 3-stage workflow clearly**: +### Core Structure Improvements +- **Front-load the 3-stage workflow** as the primary mental model: 1. Creating a change proposal (proposal.md, spec deltas, design.md, tasks.md) 2. Implementing a change proposal (following tasks, marking completion) 3. Archiving the change proposal (using archive command after deployment) -- **Update CLI command documentation** to match current implementation: - - Document `openspec show` command with proper flags and interactive mode - - Document `openspec archive` command with --skip-specs flag - - Document `openspec validate` command options - - Remove references to deprecated commands -- **Add best practices section** for AI agents on being brief and avoiding ambiguity -- **Consolidate redundant sections** to reduce overall instruction length +- **Reduce instruction length by 50%** while maintaining all critical information +- **Restructure with clear hierarchy**: Core Workflow → Quick Start → Commands → Details → Edge Cases + +### Decision Clarity Enhancements +- **Add clear decision trees** for common scenarios (bug vs feature, proposal needed vs not) +- **Remove ambiguous conditions** that confuse agent decision-making +- **Add "Before Any Task" checklist** for context gathering + +### CLI Documentation Updates +- **Document current commands** with all flags and interactive modes: + - `openspec show` - unified display with auto-detection + - `openspec archive` - with --skip-specs for tooling changes + - `openspec validate` - with --strict and batch modes +- **Remove deprecated command references** (noun-first patterns) +- **Add concrete examples** for each command variation + +### Agent-Specific Improvements +- **Tool selection matrix** - When to use Grep vs Glob vs Read +- **Error recovery patterns** - How to handle common failures +- **Context management guide** - What to read before starting tasks +- **Verification workflows** - How to confirm changes are correct + +### Best Practices Section +- **Be concise** - One-line answers when appropriate +- **Be specific** - Use exact file paths and line numbers (file.ts:42) +- **Start simple** - Default to <100 lines, single-file implementations +- **Justify complexity** - Require data/metrics for any optimization ## Impact diff --git a/openspec/changes/update-agent-instructions/tasks.md b/openspec/changes/update-agent-instructions/tasks.md index 01879c42..64be0fd4 100644 --- a/openspec/changes/update-agent-instructions/tasks.md +++ b/openspec/changes/update-agent-instructions/tasks.md @@ -1,25 +1,41 @@ # Implementation Tasks -## 1. Update OpenSpec README.md -- [ ] 1.1 Replace current README.md content with streamlined version -- [ ] 1.2 Ensure three-stage workflow is clearly documented -- [ ] 1.3 Update CLI command documentation to match current implementation -- [ ] 1.4 Add best practices section for AI agents -- [ ] 1.5 Remove redundant or verbose sections +## 1. Restructure OpenSpec README.md +- [ ] 1.1 Front-load the three-stage workflow as primary content +- [ ] 1.2 Restructure with hierarchy: Core Workflow → Quick Start → Commands → Details → Edge Cases +- [ ] 1.3 Reduce total length by 50% (target: ~285 lines from current ~575) +- [ ] 1.4 Add "Before Any Task" context-gathering checklist -## 2. Update CLAUDE.md Template -- [ ] 2.1 Update `src/core/templates/claude-template.ts` with new template content -- [ ] 2.2 Include three-stage workflow documentation -- [ ] 2.3 Add quick CLI reference section -- [ ] 2.4 Ensure complexity management section is retained +## 2. Add Decision Clarity +- [ ] 2.1 Create clear decision trees for "Create Proposal?" scenarios +- [ ] 2.2 Remove ambiguous conditions that confuse agents +- [ ] 2.3 Add concrete examples for each decision branch +- [ ] 2.4 Simplify bug vs feature determination logic -## 3. Testing and Validation -- [ ] 3.1 Run `openspec init` in a test directory to verify new CLAUDE.md generation -- [ ] 3.2 Validate that all CLI commands documented actually work -- [ ] 3.3 Run `openspec validate` to ensure no structural issues +## 3. Update CLI Documentation +- [ ] 3.1 Document `openspec show` with all flags and interactive mode +- [ ] 3.2 Document `openspec archive` with --skip-specs option +- [ ] 3.3 Document `openspec validate` with --strict and batch modes +- [ ] 3.4 Remove all deprecated noun-first command references +- [ ] 3.5 Add concrete usage examples for each command variation -## 4. Documentation Review -- [ ] 4.1 Ensure all instructions are concise and action-oriented -- [ ] 4.2 Remove any ambiguous language -- [ ] 4.3 Verify file paths and examples are accurate -- [ ] 4.4 Check that the instructions are <50% of original length while retaining all critical information \ No newline at end of file +## 4. Add Agent-Specific Sections +- [ ] 4.1 Create tool selection matrix (Grep vs Glob vs Read) +- [ ] 4.2 Add error recovery patterns section +- [ ] 4.3 Add context management guide +- [ ] 4.4 Add verification workflows section +- [ ] 4.5 Add best practices section (concise, specific, simple) + +## 5. Update CLAUDE.md Template +- [ ] 5.1 Update `src/core/templates/claude-template.ts` with streamlined content +- [ ] 5.2 Include three-stage workflow prominently +- [ ] 5.3 Add quick CLI reference +- [ ] 5.4 Add "Before Any Task" checklist +- [ ] 5.5 Keep complexity management principles + +## 6. Testing and Validation +- [ ] 6.1 Test all documented CLI commands for accuracy +- [ ] 6.2 Run `openspec init` to verify CLAUDE.md generation +- [ ] 6.3 Validate instruction clarity with example scenarios +- [ ] 6.4 Ensure no critical information was lost in streamlining +- [ ] 6.5 Verify decision trees eliminate ambiguity \ No newline at end of file From 07df6c97c9712ae14ea98ec50bec59b4b0c11bde Mon Sep 17 00:00:00 2001 From: Tabish Bidiwale Date: Mon, 25 Aug 2025 15:21:09 +1000 Subject: [PATCH 4/6] feat: add comprehensive CLI documentation and spec discovery workflow - 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 --- .../update-agent-instructions/design.md | 15 ++++++--- .../update-agent-instructions/proposal.md | 27 +++++++++++++--- .../update-agent-instructions/tasks.md | 31 ++++++++++++------- 3 files changed, 52 insertions(+), 21 deletions(-) diff --git a/openspec/changes/update-agent-instructions/design.md b/openspec/changes/update-agent-instructions/design.md index 91e6021a..4c493431 100644 --- a/openspec/changes/update-agent-instructions/design.md +++ b/openspec/changes/update-agent-instructions/design.md @@ -18,14 +18,21 @@ The workflow is now prominently featured as a core concept: This structure helps agents understand the lifecycle and their role at each stage. ### CLI Documentation Updates -- Focus on the unified `openspec show` command as primary interface -- Document interactive mode capabilities -- Include all current flags and options -- Remove references to deprecated noun-first commands +- **Comprehensive command coverage** - All 9 primary commands documented +- **`openspec list` prominence** - Essential for discovering changes and specs +- **Interactive mode documentation** - How agents can use prompts effectively +- **Complete flag documentation** - All options like --json, --type, --skip-specs +- **Deprecation cleanup** - Remove noun-first patterns (openspec change show) ### Agent-Specific Enhancements Based on industry best practices for coding agents (Claude Code, Cursor, etc.): +**Spec Discovery Workflow** +- Always check existing specs before creating new ones +- Use `openspec list --specs` to discover current capabilities +- Prefer modifying existing specs over creating duplicates +- Prevents fragmentation and maintains coherent architecture + **Decision Clarity** - Clear decision trees eliminating ambiguous conditions - Concrete examples for each decision branch diff --git a/openspec/changes/update-agent-instructions/proposal.md b/openspec/changes/update-agent-instructions/proposal.md index b41c3b0d..67f5b6bf 100644 --- a/openspec/changes/update-agent-instructions/proposal.md +++ b/openspec/changes/update-agent-instructions/proposal.md @@ -18,16 +18,33 @@ The current OpenSpec agent instructions need updates to follow best practices fo - **Add clear decision trees** for common scenarios (bug vs feature, proposal needed vs not) - **Remove ambiguous conditions** that confuse agent decision-making - **Add "Before Any Task" checklist** for context gathering +- **Add "Before Creating Specs" rule** - Always check existing specs first to avoid duplicates ### CLI Documentation Updates -- **Document current commands** with all flags and interactive modes: - - `openspec show` - unified display with auto-detection - - `openspec archive` - with --skip-specs for tooling changes - - `openspec validate` - with --strict and batch modes -- **Remove deprecated command references** (noun-first patterns) +- **Complete command documentation** with all current functionality: + - `openspec init [path]` - Initialize OpenSpec in a project + - `openspec list` - List all active changes (default) + - `openspec list --specs` - List all specifications + - `openspec show [item]` - Display change or spec with auto-detection + - `openspec show` - Interactive mode for selection + - `openspec diff [change]` - Show spec differences for a change + - `openspec validate [item]` - Validate changes or specs + - `openspec archive [change]` - Archive completed change after deployment + - `openspec update [path]` - Update OpenSpec instruction files +- **Document all flags and options**: + - `--json` output format for programmatic use + - `--type change|spec` for disambiguation + - `--skip-specs` for tooling-only archives + - `--strict` for strict validation mode + - `--no-interactive` to disable prompts +- **Remove deprecated command references** (noun-first patterns like `openspec change show`) - **Add concrete examples** for each command variation ### Agent-Specific Improvements +- **Spec discovery workflow** - Always check existing specs before creating new ones: + - Use `openspec list --specs` to see all current specs + - Check if capability already exists before creating + - Prefer modifying existing specs over creating duplicates - **Tool selection matrix** - When to use Grep vs Glob vs Read - **Error recovery patterns** - How to handle common failures - **Context management guide** - What to read before starting tasks diff --git a/openspec/changes/update-agent-instructions/tasks.md b/openspec/changes/update-agent-instructions/tasks.md index 64be0fd4..da0f525f 100644 --- a/openspec/changes/update-agent-instructions/tasks.md +++ b/openspec/changes/update-agent-instructions/tasks.md @@ -5,6 +5,7 @@ - [ ] 1.2 Restructure with hierarchy: Core Workflow → Quick Start → Commands → Details → Edge Cases - [ ] 1.3 Reduce total length by 50% (target: ~285 lines from current ~575) - [ ] 1.4 Add "Before Any Task" context-gathering checklist +- [ ] 1.5 Add "Before Creating Specs" rule to check existing specs first ## 2. Add Decision Clarity - [ ] 2.1 Create clear decision trees for "Create Proposal?" scenarios @@ -13,25 +14,31 @@ - [ ] 2.4 Simplify bug vs feature determination logic ## 3. Update CLI Documentation -- [ ] 3.1 Document `openspec show` with all flags and interactive mode -- [ ] 3.2 Document `openspec archive` with --skip-specs option -- [ ] 3.3 Document `openspec validate` with --strict and batch modes -- [ ] 3.4 Remove all deprecated noun-first command references -- [ ] 3.5 Add concrete usage examples for each command variation +- [ ] 3.1 Document `openspec list` and `openspec list --specs` commands +- [ ] 3.2 Document `openspec show` with all flags and interactive mode +- [ ] 3.3 Document `openspec diff [change]` for viewing spec differences +- [ ] 3.4 Document `openspec archive` with --skip-specs option +- [ ] 3.5 Document `openspec validate` with --strict and batch modes +- [ ] 3.6 Document `openspec init` and `openspec update` commands +- [ ] 3.7 Remove all deprecated noun-first command references +- [ ] 3.8 Add concrete usage examples for each command variation +- [ ] 3.9 Document all flags: --json, --type, --no-interactive, etc. ## 4. Add Agent-Specific Sections -- [ ] 4.1 Create tool selection matrix (Grep vs Glob vs Read) -- [ ] 4.2 Add error recovery patterns section -- [ ] 4.3 Add context management guide -- [ ] 4.4 Add verification workflows section -- [ ] 4.5 Add best practices section (concise, specific, simple) +- [ ] 4.1 Add spec discovery workflow (check existing before creating) +- [ ] 4.2 Create tool selection matrix (Grep vs Glob vs Read) +- [ ] 4.3 Add error recovery patterns section +- [ ] 4.4 Add context management guide +- [ ] 4.5 Add verification workflows section +- [ ] 4.6 Add best practices section (concise, specific, simple) ## 5. Update CLAUDE.md Template - [ ] 5.1 Update `src/core/templates/claude-template.ts` with streamlined content - [ ] 5.2 Include three-stage workflow prominently -- [ ] 5.3 Add quick CLI reference +- [ ] 5.3 Add comprehensive CLI quick reference (list, show, diff, archive, etc.) - [ ] 5.4 Add "Before Any Task" checklist -- [ ] 5.5 Keep complexity management principles +- [ ] 5.5 Add "Before Creating Specs" rule +- [ ] 5.6 Keep complexity management principles ## 6. Testing and Validation - [ ] 6.1 Test all documented CLI commands for accuracy From fae08072a94c9016766abcc447f611bad5ca5840 Mon Sep 17 00:00:00 2001 From: Tabish Bidiwale Date: Mon, 25 Aug 2025 15:25:49 +1000 Subject: [PATCH 5/6] feat: add explicit implementation workflow for Stage 2 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- .../changes/update-agent-instructions/design.md | 16 ++++++++++++++-- .../update-agent-instructions/proposal.md | 14 +++++++++++++- .../changes/update-agent-instructions/tasks.md | 16 +++++++++------- 3 files changed, 36 insertions(+), 10 deletions(-) diff --git a/openspec/changes/update-agent-instructions/design.md b/openspec/changes/update-agent-instructions/design.md index 4c493431..2eceeb10 100644 --- a/openspec/changes/update-agent-instructions/design.md +++ b/openspec/changes/update-agent-instructions/design.md @@ -12,10 +12,15 @@ ### Three-Stage Workflow Documentation The workflow is now prominently featured as a core concept: 1. **Creating** - Proposal generation phase -2. **Implementing** - Code development phase +2. **Implementing** - Code development phase with explicit steps: + - Read proposal.md for understanding + - Read design.md for technical context + - Read tasks.md for checklist + - Implement tasks sequentially + - Mark complete immediately after each task 3. **Archiving** - Post-deployment finalization phase -This structure helps agents understand the lifecycle and their role at each stage. +This structure helps agents understand the lifecycle and their role at each stage. The implementation phase is particularly detailed to prevent common mistakes like skipping documentation or batching task completion. ### CLI Documentation Updates - **Comprehensive command coverage** - All 9 primary commands documented @@ -27,6 +32,13 @@ This structure helps agents understand the lifecycle and their role at each stag ### Agent-Specific Enhancements Based on industry best practices for coding agents (Claude Code, Cursor, etc.): +**Implementation Workflow** +- Explicit steps prevent skipping critical context +- Reading proposal/design first ensures understanding before coding +- Sequential task completion maintains focus +- Immediate marking prevents losing track of progress +- Addresses common failure mode: jumping straight to code + **Spec Discovery Workflow** - Always check existing specs before creating new ones - Use `openspec list --specs` to discover current capabilities diff --git a/openspec/changes/update-agent-instructions/proposal.md b/openspec/changes/update-agent-instructions/proposal.md index 67f5b6bf..58ed8b0f 100644 --- a/openspec/changes/update-agent-instructions/proposal.md +++ b/openspec/changes/update-agent-instructions/proposal.md @@ -9,7 +9,12 @@ The current OpenSpec agent instructions need updates to follow best practices fo ### Core Structure Improvements - **Front-load the 3-stage workflow** as the primary mental model: 1. Creating a change proposal (proposal.md, spec deltas, design.md, tasks.md) - 2. Implementing a change proposal (following tasks, marking completion) + 2. Implementing a change proposal: + - First read proposal.md to understand the change + - Read design.md if it exists for technical context + - Read tasks.md for the implementation checklist + - Complete tasks one by one + - Mark each task complete immediately after finishing 3. Archiving the change proposal (using archive command after deployment) - **Reduce instruction length by 50%** while maintaining all critical information - **Restructure with clear hierarchy**: Core Workflow → Quick Start → Commands → Details → Edge Cases @@ -41,6 +46,13 @@ The current OpenSpec agent instructions need updates to follow best practices fo - **Add concrete examples** for each command variation ### Agent-Specific Improvements +- **Implementation workflow** - Clear step-by-step process: + 1. Read proposal.md to understand what's being built + 2. Read design.md (if exists) for technical decisions + 3. Read tasks.md for the implementation checklist + 4. Implement tasks one by one in order + 5. Mark each task complete immediately: `- [x] Task completed` + 6. Never skip ahead or batch task completion - **Spec discovery workflow** - Always check existing specs before creating new ones: - Use `openspec list --specs` to see all current specs - Check if capability already exists before creating diff --git a/openspec/changes/update-agent-instructions/tasks.md b/openspec/changes/update-agent-instructions/tasks.md index da0f525f..195900ea 100644 --- a/openspec/changes/update-agent-instructions/tasks.md +++ b/openspec/changes/update-agent-instructions/tasks.md @@ -7,11 +7,12 @@ - [ ] 1.4 Add "Before Any Task" context-gathering checklist - [ ] 1.5 Add "Before Creating Specs" rule to check existing specs first -## 2. Add Decision Clarity +## 2. Add Decision Clarity - [ ] 2.1 Create clear decision trees for "Create Proposal?" scenarios - [ ] 2.2 Remove ambiguous conditions that confuse agents - [ ] 2.3 Add concrete examples for each decision branch - [ ] 2.4 Simplify bug vs feature determination logic +- [ ] 2.5 Add explicit Stage 2 implementation steps (read → implement → mark complete) ## 3. Update CLI Documentation - [ ] 3.1 Document `openspec list` and `openspec list --specs` commands @@ -25,12 +26,13 @@ - [ ] 3.9 Document all flags: --json, --type, --no-interactive, etc. ## 4. Add Agent-Specific Sections -- [ ] 4.1 Add spec discovery workflow (check existing before creating) -- [ ] 4.2 Create tool selection matrix (Grep vs Glob vs Read) -- [ ] 4.3 Add error recovery patterns section -- [ ] 4.4 Add context management guide -- [ ] 4.5 Add verification workflows section -- [ ] 4.6 Add best practices section (concise, specific, simple) +- [ ] 4.1 Add implementation workflow (read docs → implement tasks → mark complete) +- [ ] 4.2 Add spec discovery workflow (check existing before creating) +- [ ] 4.3 Create tool selection matrix (Grep vs Glob vs Read) +- [ ] 4.4 Add error recovery patterns section +- [ ] 4.5 Add context management guide +- [ ] 4.6 Add verification workflows section +- [ ] 4.7 Add best practices section (concise, specific, simple) ## 5. Update CLAUDE.md Template - [ ] 5.1 Update `src/core/templates/claude-template.ts` with streamlined content From 1a3bfae784928bb029a9be6485686118c0affb6a Mon Sep 17 00:00:00 2001 From: Tabish Bidiwale Date: Mon, 25 Aug 2025 15:31:35 +1000 Subject: [PATCH 6/6] feat: add comprehensive retrospective-based improvements 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 --- .../update-agent-instructions/design.md | 20 ++++++ .../update-agent-instructions/proposal.md | 37 +++++++++++ .../update-agent-instructions/tasks.md | 65 ++++++++++++------- 3 files changed, 99 insertions(+), 23 deletions(-) diff --git a/openspec/changes/update-agent-instructions/design.md b/openspec/changes/update-agent-instructions/design.md index 2eceeb10..3293b10d 100644 --- a/openspec/changes/update-agent-instructions/design.md +++ b/openspec/changes/update-agent-instructions/design.md @@ -60,6 +60,19 @@ Based on industry best practices for coding agents (Claude Code, Cursor, etc.): - What to read before starting any work - How to maintain state across interactions +**Spec File Structure Documentation** +- Complete examples with ADDED/MODIFIED/REMOVED sections +- Critical scenario formatting (#### Scenario: headers) +- Delta file location clarity (changes/{name}/specs/) +- Addresses most common creation errors from retrospective + +**Troubleshooting and Debugging** +- Common error messages with solutions +- Delta detection debugging steps +- Validation best practices +- JSON output for inspection +- Prevents hours of frustration from silent failures + **Best Practices** - Be concise (one-line answers when appropriate) - Be specific (file.ts:42 line references) @@ -80,11 +93,18 @@ Based on industry best practices for coding agents (Claude Code, Cursor, etc.): - Addresses common failure modes (ambiguous decisions, missing context) - Optimizes for LLM strengths (pattern matching) vs weaknesses (calculations) +**Addressing Critical Pain Points (from Retrospective)** +- **Scenario formatting** - Biggest struggle, now explicitly documented with examples +- **Complete spec structure** - Full examples prevent structural errors +- **Delta detection issues** - Debugging commands help diagnose problems +- **Silent parsing failures** - Troubleshooting section explains common issues + **Practical Impact** - Faster agent comprehension of tasks - Fewer misinterpretations of requirements - More consistent implementation quality - Better error recovery when things go wrong +- Prevents the most common errors identified in user experience ## Trade-offs diff --git a/openspec/changes/update-agent-instructions/proposal.md b/openspec/changes/update-agent-instructions/proposal.md index 58ed8b0f..0ac9e58b 100644 --- a/openspec/changes/update-agent-instructions/proposal.md +++ b/openspec/changes/update-agent-instructions/proposal.md @@ -44,6 +44,43 @@ The current OpenSpec agent instructions need updates to follow best practices fo - `--no-interactive` to disable prompts - **Remove deprecated command references** (noun-first patterns like `openspec change show`) - **Add concrete examples** for each command variation +- **Document debugging commands**: + - `openspec show [change] --json --deltas-only` for inspecting deltas + - `openspec validate [change] --strict` for comprehensive validation + +### Spec File Structure Documentation +- **Complete spec file examples** showing proper structure: + ```markdown + ## ADDED Requirements + ### Requirement: Clear requirement statement + The system SHALL provide the functionality... + + #### Scenario: Descriptive scenario name + - **WHEN** condition occurs + - **THEN** expected outcome + - **AND** additional outcomes + ``` +- **Scenario formatting requirements** (critical - most common error): + - MUST use `#### Scenario:` headers (4 hashtags) + - NOT bullet lists or bold text + - Each requirement MUST have at least one scenario +- **Delta file location** - Clear explanation: + - Spec files go in `changes/{name}/specs/` directory + - Deltas are automatically extracted from these files + - Use operation prefixes: ADDED, MODIFIED, REMOVED, RENAMED + +### Troubleshooting Section +- **Common errors and solutions**: + - "Change must have at least one delta" → Check specs/ directory exists with .md files + - "Requirement must have at least one scenario" → Check scenario uses `#### Scenario:` format + - Silent scenario parsing failures → Verify exact header format +- **Delta detection debugging**: + - Use `openspec show [change] --json --deltas-only` to inspect parsed deltas + - Check that spec files have operation prefixes (## ADDED Requirements) + - Verify specs/ subdirectory structure +- **Validation best practices**: + - Always use `--strict` flag for comprehensive checks + - Use JSON output for debugging: `--json | jq '.deltas'` ### Agent-Specific Improvements - **Implementation workflow** - Clear step-by-step process: diff --git a/openspec/changes/update-agent-instructions/tasks.md b/openspec/changes/update-agent-instructions/tasks.md index 195900ea..a2eee26a 100644 --- a/openspec/changes/update-agent-instructions/tasks.md +++ b/openspec/changes/update-agent-instructions/tasks.md @@ -24,27 +24,46 @@ - [ ] 3.7 Remove all deprecated noun-first command references - [ ] 3.8 Add concrete usage examples for each command variation - [ ] 3.9 Document all flags: --json, --type, --no-interactive, etc. +- [ ] 3.10 Document debugging commands: `show --json --deltas-only` -## 4. Add Agent-Specific Sections -- [ ] 4.1 Add implementation workflow (read docs → implement tasks → mark complete) -- [ ] 4.2 Add spec discovery workflow (check existing before creating) -- [ ] 4.3 Create tool selection matrix (Grep vs Glob vs Read) -- [ ] 4.4 Add error recovery patterns section -- [ ] 4.5 Add context management guide -- [ ] 4.6 Add verification workflows section -- [ ] 4.7 Add best practices section (concise, specific, simple) - -## 5. Update CLAUDE.md Template -- [ ] 5.1 Update `src/core/templates/claude-template.ts` with streamlined content -- [ ] 5.2 Include three-stage workflow prominently -- [ ] 5.3 Add comprehensive CLI quick reference (list, show, diff, archive, etc.) -- [ ] 5.4 Add "Before Any Task" checklist -- [ ] 5.5 Add "Before Creating Specs" rule -- [ ] 5.6 Keep complexity management principles - -## 6. Testing and Validation -- [ ] 6.1 Test all documented CLI commands for accuracy -- [ ] 6.2 Run `openspec init` to verify CLAUDE.md generation -- [ ] 6.3 Validate instruction clarity with example scenarios -- [ ] 6.4 Ensure no critical information was lost in streamlining -- [ ] 6.5 Verify decision trees eliminate ambiguity \ No newline at end of file +## 4. Add Spec File Documentation +- [ ] 4.1 Add complete spec file structure example with ADDED/MODIFIED sections +- [ ] 4.2 Document scenario formatting requirements (#### Scenario: headers) +- [ ] 4.3 Explain delta file location (changes/{name}/specs/ directory) +- [ ] 4.4 Show how deltas are automatically extracted +- [ ] 4.5 Include warning about most common error (scenario formatting) + +## 5. Add Troubleshooting Section +- [ ] 5.1 Document common errors and their solutions +- [ ] 5.2 Add delta detection debugging steps +- [ ] 5.3 Include validation best practices (--strict flag) +- [ ] 5.4 Show how to use JSON output for debugging +- [ ] 5.5 Add examples of silent parsing failures + +## 6. Add Agent-Specific Sections +- [ ] 6.1 Add implementation workflow (read docs → implement tasks → mark complete) +- [ ] 6.2 Add spec discovery workflow (check existing before creating) +- [ ] 6.3 Create tool selection matrix (Grep vs Glob vs Read) +- [ ] 6.4 Add error recovery patterns section +- [ ] 6.5 Add context management guide +- [ ] 6.6 Add verification workflows section +- [ ] 6.7 Add best practices section (concise, specific, simple) + +## 7. Update CLAUDE.md Template +- [ ] 7.1 Update `src/core/templates/claude-template.ts` with streamlined content +- [ ] 7.2 Include three-stage workflow prominently +- [ ] 7.3 Add comprehensive CLI quick reference (list, show, diff, archive, etc.) +- [ ] 7.4 Add "Before Any Task" checklist +- [ ] 7.5 Add "Before Creating Specs" rule +- [ ] 7.6 Keep complexity management principles +- [ ] 7.7 Add critical scenario formatting note (#### Scenario: headers) +- [ ] 7.8 Include debugging command reference + +## 8. Testing and Validation +- [ ] 8.1 Test all documented CLI commands for accuracy +- [ ] 8.2 Run `openspec init` to verify CLAUDE.md generation +- [ ] 8.3 Validate instruction clarity with example scenarios +- [ ] 8.4 Ensure no critical information was lost in streamlining +- [ ] 8.5 Verify decision trees eliminate ambiguity +- [ ] 8.6 Test scenario formatting examples work correctly +- [ ] 8.7 Verify troubleshooting steps resolve common errors \ No newline at end of file