fix: prevent agents from creating extra files in spec change folders

Author: lindoelio

packages/cli/src/core/validate/spec.ts

@@ -13,6 +13,7 @@ import { extractDeclaredDesignElementIds } from './shared/ids.js';
 import { verifyDesignFile } from './design.js';
 import { verifyTasksFile } from './tasks.js';
 import { verifyRequirementsFile } from './requirements.js';
+import { verifySpecStructure } from './structure.js';
 
 const SKILL_DOCS = {
   requirements: 'skills/spec-driven-requirements-writer/SKILL.md',
@@ -31,14 +32,30 @@ interface SpecValidationResult extends ValidationResult {
   };
 }
 
-function verifyCompleteSpec(slug: string, targetDir: string): SpecValidationResult {
+async function verifyCompleteSpec(slug: string, targetDir: string): Promise<SpecValidationResult> {
   const errors: ValidationError[] = [];
   const requirementsErrors: string[] = [];
   const designErrors: string[] = [];
   const tasksErrors: string[] = [];
 
   const specDir = path.join(targetDir, '.specs', 'changes', slug);
 
+  const structureResult = await verifySpecStructure(slug, targetDir);
+  if (!structureResult.valid) {
+    for (const err of structureResult.errors) {
+      errors.push(err);
+    }
+  }
+  
+  if (structureResult.unexpectedFiles.length > 0) {
+    errors.push({
+      errorType: 'Structure Error',
+      context: `Unexpected files found: ${structureResult.unexpectedFiles.join(', ')}`,
+      message: `Unexpected files found`,
+      suggestedFix: 'Only requirements.md, design.md, and tasks.md are allowed. Remove or rename extra files'
+    });
+  }
+  
   let requirementsContent = '';
   let designContent = '';
   let tasksContent = '';
@@ -156,7 +173,7 @@ export function createSpecCommand(): Command {
     .option('--target-dir <path>', 'Project root directory', process.cwd())
     .option('--format <text|json>', 'Output format (text or json)', 'text')
     .action(async (slug: string, opts: { targetDir: string; format: string }) => {
-      const result = verifyCompleteSpec(slug, opts.targetDir);
+      const result = await verifyCompleteSpec(slug, opts.targetDir);
 
       if (opts.format === 'json') {
         console.log(formatValidationResult(result, 'json'));

packages/cli/src/core/validate/structure.ts

@@ -19,7 +19,7 @@ interface StructureValidationResult extends ValidationResult {
   unexpectedFiles: string[];
 }
 
-async function verifySpecStructure(slug: string, targetDir: string): Promise<StructureValidationResult> {
+export async function verifySpecStructure(slug: string, targetDir: string): Promise<StructureValidationResult> {
   const errors: Array<{ line?: number; errorType: string; context?: string; message: string; suggestedFix?: string }> = [];
   const warnings: Array<{ line?: number; message: string }> = [];
   const specDir = path.join(targetDir, '.specs', 'changes', slug);

packages/cli/templates/universal/agents/spec-driven.agent.md

@@ -16,7 +16,7 @@ You MUST enforce this lifecycle exactly:
 - Never skip phases, even if the user asks to implement immediately.
 - If there is no approved `.specs/changes/<slug>/requirements.md`, always start with requirements.
 - Before Phase 4 is explicitly approved by the human, do not write implementation code.
-- Before Phase 4 approval, only write files under `.specs/changes/<slug>/`.
+- Before Phase 4 approval, only write the three spec files under `.specs/changes/<slug>/`: requirements.md, design.md, tasks.md. No other files are permitted in this directory.
 - Every phase transition requires explicit human approval.
 - For requirements, design, and tasks, always validate and write the artifact first, then ask whether to proceed.
 

packages/cli/templates/universal/skills/agent-work-auditor/references/migration/phase-0-inventory.md

@@ -85,8 +85,4 @@ The inventory must satisfy:
 2. **Component registry complete** — All significant modules catalogued
 3. **Interfaces documented** — All external APIs captured
 4. **Side effects logged** — All observable side effects recorded
-5. **Assumptions documented** — No critical assumption left unstated
-
-## Output Location
-
-Inventory is saved to `.specs/changes/{slug}/codebase-inventory.md`
+5. **Assumptions documented** — No critical assumption left unstated

packages/cli/templates/universal/skills/spec-driven-requirements-writer/SKILL.md

@@ -370,3 +370,7 @@ This ensures the requirements document meets quality standards across:
 - **Functionality**: Complete requirements, clear acceptance criteria, no gaps
 
 The quality-grading skill will auto-fix issues scoring below 4 and provide actionable suggestions for remaining gaps.
+
+## Things To Avoid
+
+- Creating additional files in `.specs/changes/<slug>/`. Only write requirements.md for this phase.

packages/cli/templates/universal/skills/spec-driven-task-decomposer/SKILL.md

@@ -405,3 +405,7 @@ Query: workflow
 ```
 
 This ensures the task breakdown aligns with team processes, testing rules, and naming conventions.
+
+## Things To Avoid
+
+- Creating additional files in `.specs/changes/<slug>/`. Only write tasks.md for this phase.

packages/cli/templates/universal/skills/spec-driven-task-implementer/SKILL.md

@@ -234,6 +234,7 @@ If work resumes after interruption:
 - marking tasks complete without verification
 - batching multiple task status updates after the fact
 - introducing secrets or sensitive data into the repository
+- creating additional files in `.specs/changes/<slug>/`. Only write to tasks.md for status updates.
 
 ## Quality Bar (Self-Check)
 

packages/cli/templates/universal/skills/spec-driven-technical-designer/SKILL.md

@@ -501,3 +501,7 @@ Query: architecture
 ```
 
 This ensures the new design aligns with existing tech stack choices, design patterns, and tooling decisions.
+
+## Things To Avoid
+
+- Creating additional files in `.specs/changes/<slug>/`. Only write design.md for this phase.