fix: clarify spec naming convention and task checkbox format (Fission-AI#595)

* fix: clarify spec naming convention and task checkbox format

- 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

* fix: clarify delta spec location for modified capabilities

Address review feedback: explicitly state that the delta spec is created
at specs/<capability>/spec.md, not in openspec/specs/<capability>/.

Author: TabishB

docs/opsx.md

@@ -457,7 +457,7 @@ Artifacts form a directed acyclic graph (DAG). Dependencies are **enablers**, no
   │  • Create proposal.md                   │
   │  • Create tasks.md                      │
   │  • Create design.md                     │
-  │  • Create specs/*.md                    │
+  │  • Create specs/<capability>/spec.md    │
   │                                         │
   │  No awareness of what exists or         │
   │  dependencies between artifacts         │

schemas/spec-driven/schema.yaml

@@ -34,7 +34,9 @@ artifacts:
     instruction: |
       Create specification files that define WHAT the system should do.
 
-      Create one spec file per capability/feature area in specs/<name>/spec.md.
+      Create one spec file per capability listed in the proposal's Capabilities section.
+      - New capabilities: use the exact kebab-case name from the proposal (specs/<capability>/spec.md).
+      - Modified capabilities: use the existing spec folder name from openspec/specs/<capability>/ when creating the delta spec at specs/<capability>/spec.md.
 
       Delta operations (use ## headers):
       - **ADDED Requirements**: New capabilities
@@ -110,14 +112,17 @@ artifacts:
 
   - id: tasks
     generates: tasks.md
-    description: Implementation tasks derived from specs and design
+    description: Implementation checklist with trackable tasks
     template: tasks.md
     instruction: |
       Create the task list that breaks down the implementation work.
 
+      **IMPORTANT: Follow the template below exactly.** The apply phase parses
+      checkbox format to track progress. Tasks not using `- [ ]` won't be tracked.
+
       Guidelines:
       - Group related tasks under ## numbered headings
-      - Each task is a checkbox: - [ ] X.Y Task description
+      - Each task MUST be a checkbox: `- [ ] X.Y Task description`
       - Tasks should be small enough to complete in one session
       - Order tasks by dependency (what must be done first?)
 

src/core/templates/skill-templates.ts

@@ -486,7 +486,7 @@ Common artifact patterns:
 **spec-driven schema** (proposal → specs → design → tasks):
 - **proposal.md**: Ask user about the change if not clear. Fill in Why, What Changes, Capabilities, Impact.
   - The Capabilities section is critical - each capability listed will need a spec file.
-- **specs/*.md**: Create one spec per capability listed in the proposal.
+- **specs/<capability>/spec.md**: Create one spec per capability listed in the proposal's Capabilities section (use the capability name, not the change name).
 - **design.md**: Document technical decisions, architecture, and implementation approach.
 - **tasks.md**: Break down implementation into checkboxed tasks.
 
@@ -1817,7 +1817,7 @@ Common artifact patterns:
 **spec-driven schema** (proposal → specs → design → tasks):
 - **proposal.md**: Ask user about the change if not clear. Fill in Why, What Changes, Capabilities, Impact.
   - The Capabilities section is critical - each capability listed will need a spec file.
-- **specs/*.md**: Create one spec per capability listed in the proposal.
+- **specs/<capability>/spec.md**: Create one spec per capability listed in the proposal's Capabilities section (use the capability name, not the change name).
 - **design.md**: Document technical decisions, architecture, and implementation approach.
 - **tasks.md**: Break down implementation into checkboxed tasks.