fix: clarify spec naming convention and task checkbox format

[TabishB]

Summary

• Update docs, schema, and templates to clarify that specs should be named after capabilities (specs/<capability>/spec.md), not changes
• Emphasize that tasks MUST use checkbox format (- [ ]) for apply phase tracking

Test plan

• Verify schema instructions are clear
• Verify template guidance matches schema

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Clarified spec file organization: require one spec per capability with a capability-named folder and spec.md file.
  • Updated rules for new vs. modified capabilities and refined how ADDED/MODIFIED/REMOVED/RENAMED deltas are described.
  • Strengthened implementation task artifact guidance: tasks MUST be checkboxes and adhere exactly to the template for tracking.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

Walkthrough

Documentation and templates were updated to specify per-capability spec placement using specs/<capability>/spec.md. The spec-driven schema was clarified to require exact template adherence and enforce that tasks are checkbox items for tracking during the apply phase.

Changes

Cohort / File(s)	Summary
Documentation docs/opsx.md	Replaced example artifact path from specs/*.md to specs/<capability>/spec.md.
Schema / Validation schemas/spec-driven/schema.yaml	Clarified spec file rules for new vs modified capabilities; updated handling of ADDED/MODIFIED/REMOVED/RENAMED in spec deltas; strengthened tasks artifact wording to require checklist format and stated that only checkbox tasks are tracked.
Template docs src/core/templates/skill-templates.ts	Updated two documentation sections to reference specs/<capability>/spec.md instead of specs/*.md; no functional code changes.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Possibly related PRs

• feat(cli): merge init and experimental commands #564 — Aligns repo structure to place per-capability specs under specs/<name>/spec.md.
• feat: restructure schemas as directories with templates #411 — Changes to schemas/spec-driven/schema.yaml that adjust spec-driven schema and template rules.
• Clarify scaffold proposal #310 — Related updates to spec delta organization and naming for capability-based specs.

Poem

🐰 I hop through folders, tidy and quick,
Each capability gets its own little stick.
spec.md in place, checkboxes align,
Tasks get tracked, every single line.
Hooray for order — neat, concise, and slick!

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main changes across all three modified files: it references the spec naming convention clarification (specs//spec.md pattern) and the task checkbox format requirement (MUST use checkbox format).
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[vibe-kanban-cloud]

Review Complete

Your review story is ready!

View Story

Comment !reviewfast on this PR to re-generate the story.

[greptile-apps]

Greptile Overview

Greptile Summary

This PR improves documentation clarity for the spec-driven workflow by addressing two key areas:

• Spec naming convention: Updates all references from the ambiguous specs/*.md to the explicit specs/<capability>/spec.md format, emphasizing that specs should be named after capabilities (not changes) and match the capability names listed in the proposal's Capabilities section
• Task checkbox format requirement: Adds prominent warnings in the schema that tasks MUST use checkbox format (- [ ]) for the apply phase to properly track progress

The changes are consistent across documentation (docs/opsx.md), the schema definition (schemas/spec-driven/schema.yaml), and agent templates (src/core/templates/skill-templates.ts). All modifications align with existing conventions observed in the codebase (verified against actual spec files in openspec/specs/).

Confidence Score: 5/5

• This PR is safe to merge with minimal risk - purely documentation and instructional text changes
• All changes are non-functional improvements to documentation and instructional text. The modifications improve clarity without altering any code logic, schema structure, or runtime behavior. The naming convention clarification aligns with existing practices in the codebase.
• No files require special attention

Important Files Changed

Filename	Overview
docs/opsx.md	Updated diagram to clarify spec naming convention using specs/<capability>/spec.md format - simple documentation change
schemas/spec-driven/schema.yaml	Enhanced spec and task instructions to clarify capability-based naming and emphasize required checkbox format for task tracking
src/core/templates/skill-templates.ts	Updated two instances of artifact pattern documentation to clarify spec naming convention aligns with capability names from proposal

Sequence Diagram

sequenceDiagram
    participant User
    participant Agent
    participant Proposal
    participant Schema
    participant Specs
    participant Tasks
    
    User->>Agent: Request change via /openspec
    Agent->>Schema: Read schema.yaml instructions
    Schema-->>Agent: "Create spec per capability (specs/<capability>/spec.md)"
    
    Agent->>Proposal: Create proposal.md
    Note over Proposal: Capabilities section lists:<br/>- user-auth<br/>- data-export
    
    Agent->>Schema: Read specs artifact instruction
    Schema-->>Agent: "Use exact kebab-case name from proposal"
    
    Agent->>Specs: Create specs/user-auth/spec.md
    Agent->>Specs: Create specs/data-export/spec.md
    Note over Specs: Named after CAPABILITIES,<br/>not the change name
    
    Agent->>Schema: Read tasks artifact instruction
    Schema-->>Agent: "Tasks MUST use checkbox format (- [ ])"
    
    Agent->>Tasks: Create tasks.md with checkboxes
    Note over Tasks: ## 1. Setup<br/>- [ ] 1.1 Task one<br/>- [ ] 1.2 Task two
    
    User->>Agent: Run apply phase
    Agent->>Tasks: Parse checkbox format
    Tasks-->>Agent: Track progress via checkboxes
    Agent->>Tasks: Mark completed: [x]

Loading

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@schemas/spec-driven/schema.yaml`:
- Around line 37-39: The line "Modified capabilities: use the existing spec
folder name in openspec/specs/<capability>/." is ambiguous about where the delta
spec should live; update the sentence to explicitly state that you should
reference the existing capability folder name but place the delta spec file for
the change under the change's directory at specs/<capability>/spec.md (i.e., do
not write into openspec/specs/<capability>/, only reference its folder name).
Modify the text near "Create one spec file per capability listed in the
proposal's Capabilities section." to include this clarification and an explicit
example showing the delta spec path (specs/<capability>/spec.md) while still
noting the canonical existing folder name in openspec for reference.