{
  "openapi": "3.1.0",
  "info": {
    "title": "AgileToolHub Agent Tools API",
    "version": "1.0.0",
    "description": "Deterministic JSON tools for Agile and Scrum workflows. No API key is required for these endpoints. Results are starting points for team discussion, not delivery commitments.",
    "contact": { "url": "https://agiletoolhub.com/about" }
  },
  "servers": [
    { "url": "https://agiletoolhub.com", "description": "Production" }
  ],
  "paths": {
    "/api/agent/story-point": {
      "post": {
        "operationId": "estimateStoryPoints",
        "summary": "Estimate a story with five sizing factors",
        "description": "Maps five 0-3 sizing factors to a Fibonacci story point starting estimate.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/StoryPointRequest" },
              "example": {
                "story": "Add export filters to the reporting dashboard",
                "factors": { "effort": 2, "complexity": 1, "uncertainty": 1, "risk": 0, "dependencies": 1 }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Story point estimate",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoryPointResponse" } } }
          },
          "400": { "$ref": "#/components/responses/BadRequest" }
        }
      }
    },
    "/api/agent/sprint-capacity": {
      "post": {
        "operationId": "calculateSprintCapacity",
        "summary": "Calculate recommended sprint capacity",
        "description": "Calculates maximum and recommended capacity from team availability and velocity. Recommended capacity uses an 80% buffer.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/SprintCapacityRequest" },
              "example": {
                "sprintDays": 10,
                "members": [
                  { "name": "Developer 1", "daysAvailable": 8, "velocity": 2 },
                  { "name": "Developer 2", "daysAvailable": 6, "velocity": 1.5 }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Sprint capacity result",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SprintCapacityResponse" } } }
          },
          "400": { "$ref": "#/components/responses/BadRequest" }
        }
      }
    },
    "/api/agent/user-story": {
      "post": {
        "operationId": "generateUserStory",
        "summary": "Generate a Jira-ready user story",
        "description": "Turns feature notes into a deterministic Markdown user story with acceptance criteria, dependencies, clarifications, and a quality score.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/UserStoryRequest" },
              "example": {
                "feature": "As a shopper, I want to save payment methods so checkout is faster",
                "preset": "product"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Generated user story",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentToolResponse" } } }
          },
          "400": { "$ref": "#/components/responses/BadRequest" }
        }
      }
    },
    "/api/agent/acceptance-criteria": {
      "post": {
        "operationId": "generateAcceptanceCriteria",
        "summary": "Generate testable acceptance criteria",
        "description": "Turns a story or feature note into deterministic Gherkin and/or checklist acceptance criteria.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/AcceptanceCriteriaRequest" },
              "example": {
                "story": "As a shopper, I want to save payment methods so checkout is faster",
                "format": "gherkin"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Generated acceptance criteria",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentToolResponse" } } }
          },
          "400": { "$ref": "#/components/responses/BadRequest" }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "StoryPointFactors": {
        "type": "object",
        "required": ["effort", "complexity", "uncertainty", "risk", "dependencies"],
        "properties": {
          "effort": { "type": "integer", "minimum": 0, "maximum": 3 },
          "complexity": { "type": "integer", "minimum": 0, "maximum": 3 },
          "uncertainty": { "type": "integer", "minimum": 0, "maximum": 3 },
          "risk": { "type": "integer", "minimum": 0, "maximum": 3 },
          "dependencies": { "type": "integer", "minimum": 0, "maximum": 3 }
        }
      },
      "StoryPointRequest": {
        "type": "object",
        "required": ["factors"],
        "properties": {
          "story": { "type": "string", "maxLength": 2000 },
          "factors": { "$ref": "#/components/schemas/StoryPointFactors" }
        }
      },
      "StoryPointResponse": {
        "type": "object",
        "properties": {
          "tool": { "const": "story-point-estimator" },
          "estimate": { "type": "integer", "enum": [1, 2, 3, 5, 8, 13, 21] },
          "label": { "type": "string" },
          "confidence": { "type": "string" },
          "score": { "type": "integer" },
          "maxScore": { "const": 15 },
          "highFactors": { "type": "array", "items": { "type": "string" } },
          "nextActions": { "type": "array", "items": { "type": "string" } },
          "note": { "type": "string" }
        }
      },
      "SprintCapacityMember": {
        "type": "object",
        "required": ["daysAvailable", "velocity"],
        "properties": {
          "name": { "type": "string" },
          "daysAvailable": { "type": "number", "minimum": 0 },
          "velocity": { "type": "number", "minimum": 0 }
        }
      },
      "SprintCapacityRequest": {
        "type": "object",
        "required": ["sprintDays", "members"],
        "properties": {
          "sprintDays": { "type": "integer", "minimum": 1, "maximum": 30 },
          "members": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "$ref": "#/components/schemas/SprintCapacityMember" } }
        }
      },
      "SprintCapacityResponse": {
        "type": "object",
        "properties": {
          "tool": { "const": "sprint-capacity-calculator" },
          "maxCapacity": { "type": "number" },
          "recommendedCapacity": { "type": "number" },
          "sprintDays": { "type": "integer" },
          "totalAvailableDays": { "type": "number" },
          "totalTeamDays": { "type": "number" },
          "availabilityPercent": { "type": "integer" },
          "members": { "type": "array", "items": { "$ref": "#/components/schemas/SprintCapacityMemberResult" } },
          "note": { "type": "string" }
        }
      },
      "SprintCapacityMemberResult": {
        "allOf": [
          { "$ref": "#/components/schemas/SprintCapacityMember" },
          {
            "type": "object",
            "required": ["capacity"],
            "properties": { "capacity": { "type": "number" } }
          }
        ]
      },
      "UserStoryRequest": {
        "type": "object",
        "required": ["feature"],
        "properties": {
          "feature": { "type": "string", "minLength": 3, "maxLength": 4000 },
          "user": { "type": "string" },
          "storyType": { "type": "string", "enum": ["feature", "improvement", "task"] },
          "priority": { "type": "string", "enum": ["High", "Medium", "Low"] },
          "preset": { "type": "string", "enum": ["product", "engineering", "api", "tech_debt"] }
        }
      },
      "AcceptanceCriteriaRequest": {
        "type": "object",
        "required": ["story"],
        "properties": {
          "story": { "type": "string", "minLength": 3, "maxLength": 4000 },
          "user": { "type": "string" },
          "format": { "type": "string", "enum": ["gherkin", "checklist", "both"] },
          "preset": { "type": "string", "enum": ["product", "engineering", "api", "tech_debt"] }
        }
      },
      "ContentToolResponse": {
        "type": "object",
        "required": ["tool", "markdown", "parsed", "quality", "note"],
        "properties": {
          "tool": { "type": "string" },
          "markdown": { "type": "string" },
          "parsed": { "type": "object" },
          "quality": { "$ref": "#/components/schemas/QualityResult" },
          "note": { "type": "string" }
        }
      },
      "QualityResult": {
        "type": "object",
        "required": ["score", "grade", "criteria"],
        "properties": {
          "score": { "type": "integer", "minimum": 0, "maximum": 100 },
          "grade": { "type": "string", "enum": ["Excellent", "Good", "Needs Work"] },
          "criteria": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "met": { "type": "boolean" } } } }
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "The request failed validation",
        "content": { "application/json": { "schema": { "type": "object", "required": ["error"], "properties": { "error": { "type": "string" } } } } }
      }
    }
  }
}