diff --git a/openspec/changes/add-agent-schema-selection/tasks.md b/openspec/changes/add-agent-schema-selection/tasks.md index 43a63aa2..6ee5eb44 100644 --- a/openspec/changes/add-agent-schema-selection/tasks.md +++ b/openspec/changes/add-agent-schema-selection/tasks.md @@ -1,32 +1,32 @@ ## Prerequisites -- [ ] 0.1 Implement `add-per-change-schema-metadata` change first +- [x] 0.1 Implement `add-per-change-schema-metadata` change first ## 1. Schema Discovery -- [ ] 1.1 Add CLI command or helper to list schemas with descriptions (for agent use) -- [ ] 1.2 Ensure `openspec templates --schema ` returns artifact list for any schema +- [x] 1.1 Add CLI command or helper to list schemas with descriptions (for agent use) +- [x] 1.2 Ensure `openspec templates --schema ` returns artifact list for any schema ## 2. Update New Change Skill -- [ ] 2.1 Add schema selection prompt using AskUserQuestion tool -- [ ] 2.2 Present available schemas with descriptions (spec-driven, tdd, etc.) -- [ ] 2.3 Pass selected schema to `openspec new change --schema ` -- [ ] 2.4 Update output to show which schema/workflow was selected +- [x] 2.1 Add schema selection prompt using AskUserQuestion tool +- [x] 2.2 Present available schemas with descriptions (spec-driven, tdd, etc.) +- [x] 2.3 Pass selected schema to `openspec new change --schema ` +- [x] 2.4 Update output to show which schema/workflow was selected ## 3. Update Continue Change Skill -- [ ] 3.1 Remove hardcoded artifact references (proposal, specs, design, tasks) -- [ ] 3.2 Read artifact list dynamically from `openspec status --json` -- [ ] 3.3 Adjust artifact creation guidelines to be schema-agnostic -- [ ] 3.4 Handle schema-specific artifact types (e.g., TDD's `tests` artifact) +- [x] 3.1 Remove hardcoded artifact references (proposal, specs, design, tasks) +- [x] 3.2 Read artifact list dynamically from `openspec status --json` +- [x] 3.3 Adjust artifact creation guidelines to be schema-agnostic +- [x] 3.4 Handle schema-specific artifact types (e.g., TDD's `tests` artifact) ## 4. Update Apply Change Skill -- [ ] 4.1 Make task detection work with different schema structures -- [ ] 4.2 Adjust context file reading for schema-specific artifacts +- [x] 4.1 Make task detection work with different schema structures +- [x] 4.2 Adjust context file reading for schema-specific artifacts ## 5. Documentation -- [ ] 5.1 Add schema descriptions to help text or skill instructions -- [ ] 5.2 Document when to use each schema (TDD for bug fixes, spec-driven for features, etc.) +- [x] 5.1 Add schema descriptions to help text or skill instructions +- [x] 5.2 Document when to use each schema (TDD for bug fixes, spec-driven for features, etc.) diff --git a/src/commands/artifact-workflow.ts b/src/commands/artifact-workflow.ts index bdee2437..bb0eea20 100644 --- a/src/commands/artifact-workflow.ts +++ b/src/commands/artifact-workflow.ts @@ -19,11 +19,13 @@ import { formatChangeStatus, generateInstructions, listSchemas, + listSchemasWithInfo, getSchemaDir, resolveSchema, ArtifactGraph, type ChangeStatus, type ArtifactInstructions, + type SchemaInfo, } from '../core/artifact-graph/index.js'; import { createChange, validateChangeName } from '../utils/change-utils.js'; import { getNewChangeSkillTemplate, getContinueChangeSkillTemplate, getApplyChangeSkillTemplate, getOpsxNewCommandTemplate, getOpsxContinueCommandTemplate, getOpsxApplyCommandTemplate } from '../core/templates/skill-templates.js'; @@ -820,6 +822,34 @@ ${template.content} } } +// ----------------------------------------------------------------------------- +// Schemas Command +// ----------------------------------------------------------------------------- + +interface SchemasOptions { + json?: boolean; +} + +async function schemasCommand(options: SchemasOptions): Promise { + const schemas = listSchemasWithInfo(); + + if (options.json) { + console.log(JSON.stringify(schemas, null, 2)); + return; + } + + console.log('Available schemas:'); + console.log(); + + for (const schema of schemas) { + const sourceLabel = schema.source === 'user' ? chalk.dim(' (user override)') : ''; + console.log(` ${chalk.bold(schema.name)}${sourceLabel}`); + console.log(` ${schema.description}`); + console.log(` Artifacts: ${schema.artifacts.join(' → ')}`); + console.log(); + } +} + // ----------------------------------------------------------------------------- // Command Registration // ----------------------------------------------------------------------------- @@ -884,6 +914,21 @@ export function registerArtifactWorkflowCommands(program: Command): void { } }); + // Schemas command + program + .command('schemas') + .description('[Experimental] List available workflow schemas with descriptions') + .option('--json', 'Output as JSON (for agent use)') + .action(async (options: SchemasOptions) => { + try { + await schemasCommand(options); + } catch (error) { + console.log(); + ora().fail(`Error: ${(error as Error).message}`); + process.exit(1); + } + }); + // New command group with change subcommand const newCmd = program.command('new').description('[Experimental] Create new items'); diff --git a/src/core/artifact-graph/index.ts b/src/core/artifact-graph/index.ts index a8b4bbe1..2322fec7 100644 --- a/src/core/artifact-graph/index.ts +++ b/src/core/artifact-graph/index.ts @@ -21,10 +21,12 @@ export { detectCompleted } from './state.js'; export { resolveSchema, listSchemas, + listSchemasWithInfo, getSchemaDir, getPackageSchemasDir, getUserSchemasDir, SchemaLoadError, + type SchemaInfo, } from './resolver.js'; // Instruction loading diff --git a/src/core/artifact-graph/resolver.ts b/src/core/artifact-graph/resolver.ts index 89319464..52b2620f 100644 --- a/src/core/artifact-graph/resolver.ts +++ b/src/core/artifact-graph/resolver.ts @@ -156,3 +156,71 @@ export function listSchemas(): string[] { return Array.from(schemas).sort(); } + +/** + * Schema info with metadata (name, description, artifacts). + */ +export interface SchemaInfo { + name: string; + description: string; + artifacts: string[]; + source: 'package' | 'user'; +} + +/** + * Lists all available schemas with their descriptions and artifact lists. + * Useful for agent skills to present schema selection to users. + */ +export function listSchemasWithInfo(): SchemaInfo[] { + const schemas: SchemaInfo[] = []; + const seenNames = new Set(); + + // Add user override schemas first (they take precedence) + const userDir = getUserSchemasDir(); + if (fs.existsSync(userDir)) { + for (const entry of fs.readdirSync(userDir, { withFileTypes: true })) { + if (entry.isDirectory()) { + const schemaPath = path.join(userDir, entry.name, 'schema.yaml'); + if (fs.existsSync(schemaPath)) { + try { + const schema = parseSchema(fs.readFileSync(schemaPath, 'utf-8')); + schemas.push({ + name: entry.name, + description: schema.description || '', + artifacts: schema.artifacts.map((a) => a.id), + source: 'user', + }); + seenNames.add(entry.name); + } catch { + // Skip invalid schemas + } + } + } + } + } + + // Add package built-in schemas (if not overridden) + const packageDir = getPackageSchemasDir(); + if (fs.existsSync(packageDir)) { + for (const entry of fs.readdirSync(packageDir, { withFileTypes: true })) { + if (entry.isDirectory() && !seenNames.has(entry.name)) { + const schemaPath = path.join(packageDir, entry.name, 'schema.yaml'); + if (fs.existsSync(schemaPath)) { + try { + const schema = parseSchema(fs.readFileSync(schemaPath, 'utf-8')); + schemas.push({ + name: entry.name, + description: schema.description || '', + artifacts: schema.artifacts.map((a) => a.id), + source: 'package', + }); + } catch { + // Skip invalid schemas + } + } + } + } + } + + return schemas.sort((a, b) => a.name.localeCompare(b.name)); +} diff --git a/src/core/templates/skill-templates.ts b/src/core/templates/skill-templates.ts index 23011dd7..f27ee4bf 100644 --- a/src/core/templates/skill-templates.ts +++ b/src/core/templates/skill-templates.ts @@ -37,40 +37,54 @@ export function getNewChangeSkillTemplate(): SkillTemplate { **IMPORTANT**: Do NOT proceed without understanding what the user wants to build. -2. **Create the change directory** +2. **Select a workflow schema** + + Run \`openspec schemas --json\` to get available schemas with descriptions. + + Use the **AskUserQuestion tool** to let the user choose a workflow: + - Present each schema with its description + - Mark \`spec-driven\` as "(default)" if it's available + - Example options: "spec-driven - proposal → specs → design → tasks (default)", "tdd - tests → implementation → docs" + + If user doesn't have a preference, default to \`spec-driven\`. + +3. **Create the change directory** \`\`\`bash - openspec new change "" + openspec new change "" --schema "" \`\`\` - This creates a scaffolded change at \`openspec/changes//\`. + This creates a scaffolded change at \`openspec/changes//\` with the selected schema. -3. **Show the artifact status** +4. **Show the artifact status** \`\`\`bash openspec status --change "" \`\`\` This shows which artifacts need to be created and which are ready (dependencies satisfied). -4. **Get instructions for the first artifact** - The first artifact is always \`proposal\` (no dependencies). +5. **Get instructions for the first artifact** + The first artifact depends on the schema (e.g., \`proposal\` for spec-driven, \`spec\` for tdd). + Check the status output to find the first artifact with status "ready". \`\`\`bash - openspec instructions proposal --change "" + openspec instructions --change "" \`\`\` - This outputs the template and context for creating the proposal. + This outputs the template and context for creating the first artifact. -5. **STOP and wait for user direction** +6. **STOP and wait for user direction** **Output** After completing the steps, summarize: - Change name and location -- Current status (0/4 artifacts complete) -- The template for the proposal artifact -- Prompt: "Ready to create the proposal? Just describe what this change is about and I'll draft the proposal, or ask me to continue." +- Selected schema/workflow and its artifact sequence +- Current status (0/N artifacts complete) +- The template for the first artifact +- Prompt: "Ready to create the first artifact? Just describe what this change is about and I'll draft it, or ask me to continue." **Guardrails** - Do NOT create any artifacts yet - just show the instructions -- Do NOT advance beyond showing the proposal template +- Do NOT advance beyond showing the first artifact template - If the name is invalid (not kebab-case), ask for a valid name -- If a change with that name already exists, suggest continuing that change instead` +- If a change with that name already exists, suggest continuing that change instead +- Always pass --schema to preserve the user's workflow choice` }; } @@ -94,6 +108,7 @@ export function getContinueChangeSkillTemplate(): SkillTemplate { Present the top 3-4 most recently modified changes as options, showing: - Change name + - Schema (from \`schema\` field if present, otherwise "spec-driven") - Status (e.g., "0/5 tasks", "complete", "no tasks") - How recently it was modified (from \`lastModified\` field) @@ -105,7 +120,10 @@ export function getContinueChangeSkillTemplate(): SkillTemplate { \`\`\`bash openspec status --change "" --json \`\`\` - Parse the JSON to understand current state. + Parse the JSON to understand current state. The response includes: + - \`schemaName\`: The workflow schema being used (e.g., "spec-driven", "tdd") + - \`artifacts\`: Array of artifacts with their status ("done", "ready", "blocked") + - \`isComplete\`: Boolean indicating if all artifacts are complete 3. **Act based on status**: @@ -113,7 +131,7 @@ export function getContinueChangeSkillTemplate(): SkillTemplate { **If all artifacts are complete (\`isComplete: true\`)**: - Congratulate the user - - Show final status + - Show final status including the schema used - Suggest: "All artifacts created! You can now implement this change or archive it." - STOP @@ -148,30 +166,39 @@ export function getContinueChangeSkillTemplate(): SkillTemplate { After each invocation, show: - Which artifact was created +- Schema workflow being used - Current progress (N/M complete) - What artifacts are now unlocked - Prompt: "Want to continue? Just ask me to continue or tell me what to do next." **Artifact Creation Guidelines** -When filling in templates: +The artifact types and their purpose depend on the schema. Use the \`instruction\` field from the instructions output to understand what to create. + +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. - - **IMPORTANT**: The Capabilities section is critical. Before filling it in: - - Check \`openspec/specs/\` for existing capabilities - - List new capabilities with kebab-case names (e.g., \`user-auth\`, \`data-export\`) - - List modified capabilities that need spec updates - - Each capability listed will need a corresponding spec file in the next phase. -- **specs/*.md**: Create one spec per capability listed in the proposal. Use \`specs//spec.md\` path. + - The Capabilities section is critical - each capability listed will need a spec file. +- **specs/*.md**: Create one spec per capability listed in the proposal. - **design.md**: Document technical decisions, architecture, and implementation approach. -- **tasks.md**: Break down implementation into checkboxed tasks based on specs and design. +- **tasks.md**: Break down implementation into checkboxed tasks. + +**tdd schema** (spec → tests → implementation → docs): +- **spec.md**: Feature specification defining what to build. +- **tests/*.test.ts**: Write tests BEFORE implementation (TDD red phase). +- **src/*.ts**: Implement to make tests pass (TDD green phase). +- **docs/*.md**: Document the implemented feature. + +For other schemas, follow the \`instruction\` field from the CLI output. **Guardrails** - Create ONE artifact per invocation - Always read dependency artifacts before creating a new one - Never skip artifacts or create out of order - If context is unclear, ask the user before creating -- Verify the artifact file exists after writing before marking progress` +- Verify the artifact file exists after writing before marking progress +- Use the schema's artifact sequence, don't assume specific artifact names` }; } @@ -193,19 +220,28 @@ export function getApplyChangeSkillTemplate(): SkillTemplate { Run \`openspec list --json\` to get available changes. Use the **AskUserQuestion tool** to let the user select. - Show changes that have tasks.md (implementation-ready). + Show changes that are implementation-ready (have tasks artifact). + Include the schema used for each change if available. Mark changes with incomplete tasks as "(In Progress)". **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose. -2. **Get apply instructions** +2. **Check status to understand the schema** + \`\`\`bash + openspec status --change "" --json + \`\`\` + Parse the JSON to understand: + - \`schemaName\`: The workflow being used (e.g., "spec-driven", "tdd") + - Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others) + +3. **Get apply instructions** \`\`\`bash openspec instructions apply --change "" --json \`\`\` This returns: - - Context file paths (proposal, specs, design, tasks) + - Context file paths (varies by schema - could be proposal/specs/design/tasks or spec/tests/implementation/docs) - Progress (total, complete, remaining) - Task list with status - Dynamic instruction based on current state @@ -215,28 +251,29 @@ export function getApplyChangeSkillTemplate(): SkillTemplate { - If \`state: "all_done"\`: congratulate, suggest archive - Otherwise: proceed to implementation -3. **Read context files** +4. **Read context files** - Read the files listed in \`contextFiles\`: - - \`proposal\` - why and what - - \`specs\` - requirements and scenarios (use glob pattern to find all) - - \`design\` - technical approach (if exists) - - \`tasks\` - the implementation checklist + Read the files listed in \`contextFiles\` from the apply instructions output. + The files depend on the schema being used: + - **spec-driven**: proposal, specs, design, tasks + - **tdd**: spec, tests, implementation, docs + - Other schemas: follow the contextFiles from CLI output -4. **Show current progress** +5. **Show current progress** Display: + - Schema being used - Progress: "N/M tasks complete" - Remaining tasks overview - Dynamic instruction from CLI -5. **Implement tasks (loop until done or blocked)** +6. **Implement tasks (loop until done or blocked)** For each pending task: - Show which task is being worked on - Make the code changes required - Keep changes minimal and focused - - Mark task complete in tasks.md: \`- [ ]\` → \`- [x]\` + - Mark task complete in the tasks file: \`- [ ]\` → \`- [x]\` - Continue to next task **Pause if:** @@ -245,7 +282,7 @@ export function getApplyChangeSkillTemplate(): SkillTemplate { - Error or blocker encountered → report and wait for guidance - User interrupts -6. **On completion or pause, show status** +7. **On completion or pause, show status** Display: - Tasks completed this session @@ -256,7 +293,7 @@ export function getApplyChangeSkillTemplate(): SkillTemplate { **Output During Implementation** \`\`\` -## Implementing: +## Implementing: (schema: ) Working on task 3/7: [...implementation happening...] @@ -273,6 +310,7 @@ Working on task 4/7: ## Implementation Complete **Change:** +**Schema:** **Progress:** 7/7 tasks complete ✓ ### Completed This Session @@ -289,6 +327,7 @@ All tasks complete! Ready to archive this change. ## Implementation Paused **Change:** +**Schema:** **Progress:** 4/7 tasks complete ### Issue Encountered @@ -304,18 +343,19 @@ What would you like to do? **Guardrails** - Keep going through tasks until done or blocked -- Always read context before starting (specs, design) +- Always read context files before starting (from the apply instructions output) - If task is ambiguous, pause and ask before implementing - If implementation reveals issues, pause and suggest artifact updates - Keep code changes minimal and scoped to each task - Update task checkbox immediately after completing each task - Pause on errors, blockers, or unclear requirements - don't guess +- Use contextFiles from CLI output, don't assume specific file names **Fluid Workflow Integration** This skill supports the "actions on a change" model: -- **Can be invoked anytime**: Before all artifacts are done (if tasks.md exists), after partial implementation, interleaved with other actions +- **Can be invoked anytime**: Before all artifacts are done (if tasks exist), after partial implementation, interleaved with other actions - **Allows artifact updates**: If implementation reveals design issues, suggest updating artifacts - not phase-locked, work fluidly` }; } @@ -356,40 +396,53 @@ export function getOpsxNewCommandTemplate(): CommandTemplate { **IMPORTANT**: Do NOT proceed without understanding what the user wants to build. -2. **Create the change directory** +2. **Select a workflow schema** + + Run \`openspec schemas --json\` to get available schemas with descriptions. + + Use the **AskUserQuestion tool** to let the user choose a workflow: + - Present each schema with its description + - Mark \`spec-driven\` as "(default)" if it's available + - Example options: "spec-driven - proposal → specs → design → tasks (default)", "tdd - tests → implementation → docs" + + If user doesn't have a preference, default to \`spec-driven\`. + +3. **Create the change directory** \`\`\`bash - openspec new change "" + openspec new change "" --schema "" \`\`\` - This creates a scaffolded change at \`openspec/changes//\`. + This creates a scaffolded change at \`openspec/changes//\` with the selected schema. -3. **Show the artifact status** +4. **Show the artifact status** \`\`\`bash openspec status --change "" \`\`\` This shows which artifacts need to be created and which are ready (dependencies satisfied). -4. **Get instructions for the first artifact** - The first artifact is always \`proposal\` (no dependencies). +5. **Get instructions for the first artifact** + The first artifact depends on the schema. Check the status output to find the first artifact with status "ready". \`\`\`bash - openspec instructions proposal --change "" + openspec instructions --change "" \`\`\` - This outputs the template and context for creating the proposal. + This outputs the template and context for creating the first artifact. -5. **STOP and wait for user direction** +6. **STOP and wait for user direction** **Output** After completing the steps, summarize: - Change name and location -- Current status (0/4 artifacts complete) -- The template for the proposal artifact -- Prompt: "Ready to create the proposal? Run \`/opsx:continue\` or just describe what this change is about and I'll draft the proposal." +- Selected schema/workflow and its artifact sequence +- Current status (0/N artifacts complete) +- The template for the first artifact +- Prompt: "Ready to create the first artifact? Run \`/opsx:continue\` or just describe what this change is about and I'll draft it." **Guardrails** - Do NOT create any artifacts yet - just show the instructions -- Do NOT advance beyond showing the proposal template +- Do NOT advance beyond showing the first artifact template - If the name is invalid (not kebab-case), ask for a valid name -- If a change with that name already exists, suggest using \`/opsx:continue\` instead` +- If a change with that name already exists, suggest using \`/opsx:continue\` instead +- Always pass --schema to preserve the user's workflow choice` }; } @@ -414,6 +467,7 @@ export function getOpsxContinueCommandTemplate(): CommandTemplate { Present the top 3-4 most recently modified changes as options, showing: - Change name + - Schema (from \`schema\` field if present, otherwise "spec-driven") - Status (e.g., "0/5 tasks", "complete", "no tasks") - How recently it was modified (from \`lastModified\` field) @@ -425,7 +479,10 @@ export function getOpsxContinueCommandTemplate(): CommandTemplate { \`\`\`bash openspec status --change "" --json \`\`\` - Parse the JSON to understand current state. + Parse the JSON to understand current state. The response includes: + - \`schemaName\`: The workflow schema being used (e.g., "spec-driven", "tdd") + - \`artifacts\`: Array of artifacts with their status ("done", "ready", "blocked") + - \`isComplete\`: Boolean indicating if all artifacts are complete 3. **Act based on status**: @@ -433,7 +490,7 @@ export function getOpsxContinueCommandTemplate(): CommandTemplate { **If all artifacts are complete (\`isComplete: true\`)**: - Congratulate the user - - Show final status + - Show final status including the schema used - Suggest: "All artifacts created! You can now implement this change or archive it." - STOP @@ -468,30 +525,39 @@ export function getOpsxContinueCommandTemplate(): CommandTemplate { After each invocation, show: - Which artifact was created +- Schema workflow being used - Current progress (N/M complete) - What artifacts are now unlocked - Prompt: "Run \`/opsx:continue\` to create the next artifact" **Artifact Creation Guidelines** -When filling in templates: +The artifact types and their purpose depend on the schema. Use the \`instruction\` field from the instructions output to understand what to create. + +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. - - **IMPORTANT**: The Capabilities section is critical. Before filling it in: - - Check \`openspec/specs/\` for existing capabilities - - List new capabilities with kebab-case names (e.g., \`user-auth\`, \`data-export\`) - - List modified capabilities that need spec updates - - Each capability listed will need a corresponding spec file in the next phase. -- **specs/*.md**: Create one spec per capability listed in the proposal. Use \`specs//spec.md\` path. + - The Capabilities section is critical - each capability listed will need a spec file. +- **specs/*.md**: Create one spec per capability listed in the proposal. - **design.md**: Document technical decisions, architecture, and implementation approach. -- **tasks.md**: Break down implementation into checkboxed tasks based on specs and design. +- **tasks.md**: Break down implementation into checkboxed tasks. + +**tdd schema** (spec → tests → implementation → docs): +- **spec.md**: Feature specification defining what to build. +- **tests/*.test.ts**: Write tests BEFORE implementation (TDD red phase). +- **src/*.ts**: Implement to make tests pass (TDD green phase). +- **docs/*.md**: Document the implemented feature. + +For other schemas, follow the \`instruction\` field from the CLI output. **Guardrails** - Create ONE artifact per invocation - Always read dependency artifacts before creating a new one - Never skip artifacts or create out of order - If context is unclear, ask the user before creating -- Verify the artifact file exists after writing before marking progress` +- Verify the artifact file exists after writing before marking progress +- Use the schema's artifact sequence, don't assume specific artifact names` }; } @@ -514,19 +580,28 @@ export function getOpsxApplyCommandTemplate(): CommandTemplate { Run \`openspec list --json\` to get available changes. Use the **AskUserQuestion tool** to let the user select. - Show changes that have tasks.md (implementation-ready). + Show changes that are implementation-ready (have tasks artifact). + Include the schema used for each change if available. Mark changes with incomplete tasks as "(In Progress)". **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose. -2. **Get apply instructions** +2. **Check status to understand the schema** + \`\`\`bash + openspec status --change "" --json + \`\`\` + Parse the JSON to understand: + - \`schemaName\`: The workflow being used (e.g., "spec-driven", "tdd") + - Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others) + +3. **Get apply instructions** \`\`\`bash openspec instructions apply --change "" --json \`\`\` This returns: - - Context file paths (proposal, specs, design, tasks) + - Context file paths (varies by schema) - Progress (total, complete, remaining) - Task list with status - Dynamic instruction based on current state @@ -536,28 +611,29 @@ export function getOpsxApplyCommandTemplate(): CommandTemplate { - If \`state: "all_done"\`: congratulate, suggest archive - Otherwise: proceed to implementation -3. **Read context files** +4. **Read context files** - Read the files listed in \`contextFiles\`: - - \`proposal\` - why and what - - \`specs\` - requirements and scenarios (use glob pattern to find all) - - \`design\` - technical approach (if exists) - - \`tasks\` - the implementation checklist + Read the files listed in \`contextFiles\` from the apply instructions output. + The files depend on the schema being used: + - **spec-driven**: proposal, specs, design, tasks + - **tdd**: spec, tests, implementation, docs + - Other schemas: follow the contextFiles from CLI output -4. **Show current progress** +5. **Show current progress** Display: + - Schema being used - Progress: "N/M tasks complete" - Remaining tasks overview - Dynamic instruction from CLI -5. **Implement tasks (loop until done or blocked)** +6. **Implement tasks (loop until done or blocked)** For each pending task: - Show which task is being worked on - Make the code changes required - Keep changes minimal and focused - - Mark task complete in tasks.md: \`- [ ]\` → \`- [x]\` + - Mark task complete in the tasks file: \`- [ ]\` → \`- [x]\` - Continue to next task **Pause if:** @@ -566,7 +642,7 @@ export function getOpsxApplyCommandTemplate(): CommandTemplate { - Error or blocker encountered → report and wait for guidance - User interrupts -6. **On completion or pause, show status** +7. **On completion or pause, show status** Display: - Tasks completed this session @@ -577,7 +653,7 @@ export function getOpsxApplyCommandTemplate(): CommandTemplate { **Output During Implementation** \`\`\` -## Implementing: +## Implementing: (schema: ) Working on task 3/7: [...implementation happening...] @@ -594,6 +670,7 @@ Working on task 4/7: ## Implementation Complete **Change:** +**Schema:** **Progress:** 7/7 tasks complete ✓ ### Completed This Session @@ -610,6 +687,7 @@ All tasks complete! Ready to archive this change. ## Implementation Paused **Change:** +**Schema:** **Progress:** 4/7 tasks complete ### Issue Encountered @@ -625,18 +703,19 @@ What would you like to do? **Guardrails** - Keep going through tasks until done or blocked -- Always read context before starting (specs, design) +- Always read context files before starting (from the apply instructions output) - If task is ambiguous, pause and ask before implementing - If implementation reveals issues, pause and suggest artifact updates - Keep code changes minimal and scoped to each task - Update task checkbox immediately after completing each task - Pause on errors, blockers, or unclear requirements - don't guess +- Use contextFiles from CLI output, don't assume specific file names **Fluid Workflow Integration** This skill supports the "actions on a change" model: -- **Can be invoked anytime**: Before all artifacts are done (if tasks.md exists), after partial implementation, interleaved with other actions +- **Can be invoked anytime**: Before all artifacts are done (if tasks exist), after partial implementation, interleaved with other actions - **Allows artifact updates**: If implementation reveals design issues, suggest updating artifacts - not phase-locked, work fluidly` }; }