Aperant/auto-build/spec_contract.json

{
  "$schema": "Spec Creation Contract - Defines required outputs at each phase",
  "version": "1.0.0",
  "description": "This contract defines the checkpoints and required outputs for spec creation. Each agent MUST produce the specified outputs before proceeding.",

  "phases": {
    "1_discovery": {
      "name": "Project Discovery",
      "agent": null,
      "script": "analyzer.py",
      "description": "Analyze project structure (deterministic - no AI needed)",
      "inputs": [],
      "outputs": {
        "project_index.json": {
          "required": true,
          "location": "spec_dir",
          "validation": {
            "type": "json",
            "required_fields": ["project_type"],
            "project_type_values": ["single", "monorepo"]
          }
        }
      },
      "on_failure": "retry_script"
    },

    "2_requirements": {
      "name": "Requirements Gathering",
      "agent": "spec_gatherer.md",
      "script": null,
      "description": "Interactive session to gather user requirements",
      "inputs": ["project_index.json"],
      "outputs": {
        "requirements.json": {
          "required": true,
          "location": "spec_dir",
          "validation": {
            "type": "json",
            "required_fields": ["task_description", "workflow_type", "services_involved"],
            "workflow_type_values": ["feature", "refactor", "investigation", "migration", "simple"]
          }
        }
      },
      "on_failure": "retry_agent"
    },

    "3_context": {
      "name": "Context Discovery",
      "agent": null,
      "script": "context.py",
      "description": "Find relevant files (deterministic - no AI needed)",
      "inputs": ["project_index.json", "requirements.json"],
      "outputs": {
        "context.json": {
          "required": true,
          "location": "spec_dir",
          "validation": {
            "type": "json",
            "required_fields": ["task_description"],
            "recommended_fields": ["files_to_modify", "files_to_reference", "scoped_services"]
          }
        }
      },
      "on_failure": "retry_script"
    },

    "4_spec_writing": {
      "name": "Spec Document Creation",
      "agent": "spec_writer.md",
      "script": null,
      "description": "Write the spec.md document from gathered context",
      "inputs": ["project_index.json", "requirements.json", "context.json"],
      "outputs": {
        "spec.md": {
          "required": true,
          "location": "spec_dir",
          "validation": {
            "type": "markdown",
            "required_sections": ["Overview", "Workflow Type", "Task Scope", "Success Criteria"],
            "recommended_sections": ["Files to Modify", "Files to Reference", "Requirements", "QA Acceptance Criteria"],
            "min_length": 500
          }
        }
      },
      "on_failure": "retry_agent"
    },

    "5_planning": {
      "name": "Implementation Planning",
      "agent": "planner.md",
      "script": "planner.py",
      "description": "Create the implementation plan (try script first, fall back to agent)",
      "inputs": ["spec.md", "project_index.json", "context.json"],
      "outputs": {
        "implementation_plan.json": {
          "required": true,
          "location": "spec_dir",
          "validation": {
            "type": "json",
            "required_fields": ["feature", "workflow_type", "phases"],
            "phases_validation": {
              "required_fields": ["phase", "name", "chunks"],
              "chunks_validation": {
                "required_fields": ["id", "description", "status"],
                "status_values": ["pending", "in_progress", "completed", "blocked", "failed"]
              }
            }
          }
        }
      },
      "on_failure": "retry_agent",
      "fallback_to_agent": true
    },

    "6_validation": {
      "name": "Final Validation",
      "agent": null,
      "script": "validate_spec.py",
      "description": "Validate all outputs before completion",
      "inputs": ["project_index.json", "requirements.json", "context.json", "spec.md", "implementation_plan.json"],
      "outputs": {},
      "on_failure": "report_and_fix"
    }
  },

  "recovery_strategies": {
    "retry_script": {
      "max_retries": 3,
      "action": "Re-run the Python script with same inputs"
    },
    "retry_agent": {
      "max_retries": 2,
      "action": "Invoke agent again with error context"
    },
    "report_and_fix": {
      "max_retries": 1,
      "action": "Report errors and invoke fix agent"
    }
  },

  "agents": {
    "spec_gatherer.md": {
      "purpose": "Gather requirements from user through interactive questions",
      "input_files": ["project_index.json"],
      "output_files": ["requirements.json"],
      "interactive": true
    },
    "spec_writer.md": {
      "purpose": "Write spec.md from requirements and context",
      "input_files": ["project_index.json", "requirements.json", "context.json"],
      "output_files": ["spec.md"],
      "interactive": false
    },
    "planner.md": {
      "purpose": "Create implementation_plan.json from spec",
      "input_files": ["spec.md", "project_index.json", "context.json"],
      "output_files": ["implementation_plan.json"],
      "interactive": false
    },
    "spec_fixer.md": {
      "purpose": "Fix validation errors in spec outputs",
      "input_files": ["validation_errors.json", "all spec files"],
      "output_files": ["fixed files"],
      "interactive": false
    }
  }
}