Feat/custom-template #307
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,192 @@ | ||
| import { promises as fs } from 'fs'; | ||
| import path from 'path'; | ||
|
|
||
| export type ChangeTemplateType = 'proposal' | 'tasks' | 'design' | 'spec'; | ||
|
|
||
| export interface TemplateContext { | ||
| changeId?: string; | ||
| date?: string; | ||
| capability?: string; | ||
| } | ||
|
|
||
| /** | ||
| * Default templates for change files | ||
| */ | ||
| const defaultTemplates: Record<ChangeTemplateType, string> = { | ||
| proposal: `## Why | ||
| TODO: Explain why {{changeId}} is needed | ||
|
|
||
| ## What Changes | ||
| - TODO: List changes | ||
| - Created on {{date}} | ||
|
|
||
| ## Impact | ||
| - Affected specs: TODO | ||
| - Affected code: TODO`, | ||
|
|
||
| tasks: `## 1. Implementation | ||
| - [ ] 1.1 TODO: First task for {{changeId}} | ||
| - [ ] 1.2 TODO: Second task`, | ||
|
|
||
| design: `## Context | ||
| TODO: Background and constraints for {{changeId}} | ||
|
|
||
| ## Goals / Non-Goals | ||
| - Goals: TODO | ||
| - Non-Goals: TODO | ||
|
|
||
| ## Decisions | ||
| TODO: Technical decisions and rationale | ||
|
|
||
| ## Risks / Trade-offs | ||
| TODO: Risks and mitigation strategies`, | ||
|
|
||
| spec: `## ADDED Requirements | ||
| ### Requirement: [Replace with actual requirement name] | ||
| The system SHALL [describe the requirement]. | ||
|
|
||
| #### Scenario: [Replace with scenario name] | ||
| - **WHEN** [condition] | ||
| - **THEN** [expected result]`, | ||
| }; | ||
|
|
||
| /** | ||
| * Validates that a spec template contains required tags for archive to work correctly | ||
| */ | ||
| function validateSpecTemplate(content: string): { valid: boolean; errors: string[] } { | ||
| const errors: string[] = []; | ||
|
|
||
| // Check for at least one delta section | ||
| const hasDeltaSection = /^##\s+(ADDED|MODIFIED|REMOVED|RENAMED)\s+Requirements/m.test(content); | ||
| if (!hasDeltaSection) { | ||
| errors.push('Missing required delta section (## ADDED Requirements, ## MODIFIED Requirements, etc.)'); | ||
| } | ||
|
|
||
| // Check for Requirement header | ||
| const hasRequirement = /^###\s+Requirement:/m.test(content); | ||
| if (!hasRequirement) { | ||
| errors.push('Missing required ### Requirement: header'); | ||
| } | ||
|
|
||
| // Check for Scenario header | ||
| const hasScenario = /^####\s+Scenario:/m.test(content); | ||
| if (!hasScenario) { | ||
| errors.push('Missing required #### Scenario: header'); | ||
| } | ||
|
|
||
| return { | ||
| valid: errors.length === 0, | ||
| errors, | ||
| }; | ||
| } | ||
|
|
||
| /** | ||
| * Replaces template variables with actual values | ||
| */ | ||
| function replaceVariables(content: string, context: TemplateContext): string { | ||
| let result = content; | ||
|
|
||
| if (context.changeId !== undefined) { | ||
| result = result.replace(/\{\{changeId\}\}/g, context.changeId); | ||
| } | ||
|
|
||
| if (context.date !== undefined) { | ||
| result = result.replace(/\{\{date\}\}/g, context.date); | ||
| } | ||
|
|
||
| if (context.capability !== undefined) { | ||
| result = result.replace(/\{\{capability\}\}/g, context.capability); | ||
| } | ||
|
|
||
| return result; | ||
| } | ||
|
|
||
| /** | ||
| * Manages change file templates with support for custom templates and variable substitution | ||
| */ | ||
| export class ChangeTemplateManager { | ||
| /** | ||
| * Loads a template from file system or returns default template | ||
| * @param openspecDir Path to openspec directory | ||
| * @param type Template type | ||
| * @param context Variables to replace in template | ||
| * @returns Rendered template content | ||
| */ | ||
| static async loadTemplate( | ||
| openspecDir: string, | ||
| type: ChangeTemplateType, | ||
| context: TemplateContext = {} | ||
| ): Promise<string> { | ||
| const templatePath = path.join(openspecDir, 'templates', `${type}.md.template`); | ||
|
|
||
| let content: string; | ||
| let isCustom = false; | ||
|
|
||
| try { | ||
| // Try to load custom template | ||
| content = await fs.readFile(templatePath, 'utf-8'); | ||
| isCustom = true; | ||
| } catch { | ||
| // File doesn't exist, use default | ||
| content = defaultTemplates[type]; | ||
| } | ||
|
|
||
| // Validate spec template if it's custom | ||
| if (isCustom && type === 'spec') { | ||
| const validation = validateSpecTemplate(content); | ||
| if (!validation.valid) { | ||
| console.warn( | ||
| `Warning: Custom spec template at ${templatePath} is missing required tags:\n ${validation.errors.join('\n ')}\n Falling back to default template.` | ||
| ); | ||
| content = defaultTemplates[type]; | ||
| } | ||
| } | ||
|
|
||
| // Replace variables | ||
| const rendered = replaceVariables(content, { | ||
| changeId: context.changeId || '', | ||
| date: context.date || new Date().toISOString().split('T')[0], | ||
| capability: context.capability || '', | ||
| }); | ||
|
|
||
| return rendered; | ||
| } | ||
|
|
||
| /** | ||
| * Gets the default template content for a given type | ||
| * @param type Template type | ||
| * @returns Default template content | ||
| */ | ||
| static getDefaultTemplate(type: ChangeTemplateType): string { | ||
| return defaultTemplates[type]; | ||
| } | ||
|
|
||
| /** | ||
| * Checks if custom templates directory exists | ||
| * @param openspecDir Path to openspec directory | ||
| * @returns True if templates directory exists | ||
| */ | ||
| static async hasCustomTemplates(openspecDir: string): Promise<boolean> { | ||
| const templatesDir = path.join(openspecDir, 'templates'); | ||
| try { | ||
| const stat = await fs.stat(templatesDir); | ||
| return stat.isDirectory(); | ||
| } catch { | ||
| return false; | ||
| } | ||
| } | ||
|
|
||
| /** | ||
| * Writes default templates to the templates directory | ||
| * @param openspecDir Path to openspec directory | ||
| */ | ||
| static async writeDefaultTemplates(openspecDir: string): Promise<void> { | ||
| const templatesDir = path.join(openspecDir, 'templates'); | ||
| await fs.mkdir(templatesDir, { recursive: true }); | ||
|
|
||
| for (const [type, content] of Object.entries(defaultTemplates)) { | ||
| const templatePath = path.join(templatesDir, `${type}.md.template`); | ||
| await fs.writeFile(templatePath, content, 'utf-8'); | ||
| } | ||
| } | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Hey @jax-max I try and reduce the amount of decisions an LLM has to make and try and make decisions here programatic if possible.
I have something in mind on how to acccomplish this by creating an
openspec scaffoldcommand that sets up default templates for an Agent to fill out.Check it out here: https://github.com/Fission-AI/OpenSpec/tree/main/openspec/changes/add-scaffold-command
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Hi @TabishB I've seen the changes related to the scaffold – the last update was two months ago, so I'm not sure if the plan is still moving forward.
Personally, I think the scaffold should be project-scoped rather than change-scoped. Therefore, it would be better to handle template initialization during the openspec init phase: first generate the spec, task, design, and proposal templates, then modify these templates to meet the project's specific requirements. After that, all subsequent changes should adhere to these pre-configured templates.
I’ve also thought about making decisions programmatic if possible, but I don’t want to introduce additional commands (like bash or PowerShell) the way spec-kit does.
Do you have any better suggestions? Feel free to share them – I’m open to discussing this further!
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I’ve also considered the spec file customization risk – We need to restrict users from modifying tags in spec deltas.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@TabishB By the way, I’ve already dropped you a message on Discord, PTAL , hh
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Hey @jax-max, I think we're on the same page here. The scaffold should ideally be project-scoped not change scoped, I agree!
The
openspec scaffoldshould generate whatever the project defined template is (Should default to the standard OpenSpec template structure if it has not been modified.)We can store this somewhere in
openspec/tempalate/*The job of the scaffold command will be to just make a copy of the template into whatever change directory. (So should take as input).
We then need to update the instructions to ask the agent to "fill in the documents" after creation.
I'll try and see if I can create a sequence diagram for this. We just need to be a bit careful with this change and we could possibly degrade the performance/quality of spec generation for current users.
If there's another way to test this out without affecting the core flow, I'd be keen to integrate that first.
I'll work on the scaffold tomorrow and you can let me know if it works the way you expect?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
hi @TabishB , That's awesome! I'm really looking forward to the scaffold feature. Regarding "asking the agent to 'fill in the documents' after creation", we actually prefer to handle this step manually. For large-scale backend projects, the agent’s analysis hasn’t been as effective as expected. Anyway, I’m still super excited for the scaffold to go live! Should I close the current PR?