From 2336ac62b920921039d10731fc3bf32a923c9063 Mon Sep 17 00:00:00 2001 From: Tabish Bidiwale Date: Mon, 26 Jan 2026 17:56:08 -0800 Subject: [PATCH 1/2] fix: clarify spec naming convention and task checkbox format - Update docs, schema, and templates to clarify that specs should be named after capabilities (specs//spec.md), not changes - Emphasize that tasks MUST use checkbox format for apply phase tracking --- docs/opsx.md | 2 +- schemas/spec-driven/schema.yaml | 11 ++++++++--- src/core/templates/skill-templates.ts | 4 ++-- 3 files changed, 11 insertions(+), 6 deletions(-) diff --git a/docs/opsx.md b/docs/opsx.md index 7791634236..39fd0fcbf2 100644 --- a/docs/opsx.md +++ b/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//spec.md │ │ │ │ No awareness of what exists or │ │ dependencies between artifacts │ diff --git a/schemas/spec-driven/schema.yaml b/schemas/spec-driven/schema.yaml index d4a6813495..7c0b17e2aa 100644 --- a/schemas/spec-driven/schema.yaml +++ b/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//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//spec.md). + - Modified capabilities: use the existing spec folder name in openspec/specs//. 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?) diff --git a/src/core/templates/skill-templates.ts b/src/core/templates/skill-templates.ts index dcb479307d..3330d3afe8 100644 --- a/src/core/templates/skill-templates.ts +++ b/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//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//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. From 67beb8281754c4717706e143ce649487952c4b59 Mon Sep 17 00:00:00 2001 From: Tabish Bidiwale Date: Mon, 26 Jan 2026 18:08:52 -0800 Subject: [PATCH 2/2] fix: clarify delta spec location for modified capabilities Address review feedback: explicitly state that the delta spec is created at specs//spec.md, not in openspec/specs//. --- schemas/spec-driven/schema.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/schemas/spec-driven/schema.yaml b/schemas/spec-driven/schema.yaml index 7c0b17e2aa..45f61e222b 100644 --- a/schemas/spec-driven/schema.yaml +++ b/schemas/spec-driven/schema.yaml @@ -36,7 +36,7 @@ artifacts: 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//spec.md). - - Modified capabilities: use the existing spec folder name in openspec/specs//. + - Modified capabilities: use the existing spec folder name from openspec/specs// when creating the delta spec at specs//spec.md. Delta operations (use ## headers): - **ADDED Requirements**: New capabilities