An agent-ready issue template is a pre-formatted guide for creating tasks that an AI software engineering agent can successfully understand and complete. These templates structure work with the precision of a good prompt, providing clear context, scope, and completion criteria. By using them, you translate human-centric project needs into machine-executable instructions, dramatically improving the agent’s success rate and reducing the need for rework.

Think of it like briefing a junior developer. You wouldn’t just say, “The login is broken, fix it.” You’d provide steps to reproduce the bug, point them to the relevant files, and explain what the correct behavior should be. Agent-ready templates formalize this briefing process, ensuring the AI has everything it needs to get the job done right the first time.

AI agents, like human developers, thrive on clarity and struggle with ambiguity. A well-crafted issue template acts as a structured prompt, guiding the agent toward a successful outcome by minimizing guesswork.

Here’s how they help:

• Crisp Scope: Templates force you to define the boundaries of the task. Instead of a vague goal like “improve the API,” you specify “add a last_updated field to the /users endpoint.” This precision prevents the agent from making unwanted changes or going down rabbit holes.
• Repo Path Hints: Pointing the agent to specific files or directories (/src/controllers/authController.js) saves it from wasting time and tokens scanning the entire codebase. It’s the fastest way to provide context.
• Acceptance Tests: Clear, verifiable completion criteria are crucial. Stating “The included Jest test tests/routes/user.test.js must pass” gives the agent a concrete goal and a way to validate its own work.
• Exit Criteria: Defining what “done” looks like is non-negotiable. This could be a successful test run, a linter passing, or a specific change being visible in a running application. Without it, the agent doesn’t know when to stop.

These elements combine to create a feedback loop where the agent can assess its progress and self-correct, just as a human developer would.

As AI agents become more integrated into software development workflows, the ability to assign them work effectively is becoming a critical skill. Teams that master this will ship faster, with higher quality and less overhead.

Well-defined templates offer several key advantages:

• Scalability: Standardized tasks are easier to delegate and manage, whether to a human or an AI. Templates allow you to create a backlog of agent-ready work that can be processed in parallel.
• Consistency: Templates ensure that every task, from bug fixes to documentation updates, is specified with the same level of detail, leading to more predictable outcomes.
• Efficiency: They reduce the back-and-forth that comes from poorly defined tasks. Product managers and tech leads can write an issue once, knowing the agent has everything it needs.
• Onboarding: Just as they help AI, these templates are fantastic for onboarding new human developers, providing them with a clear, concise, and actionable task list.

Ultimately, agent-ready templates are about optimizing the flow of work from idea to production in a hybrid human-AI development environment.

Here are five practical, copy-paste-ready templates for common development tasks. Use these as a starting point and adapt them to your project’s specific needs.

Purpose: To isolate and fix a specific bug. This template focuses on reproducibility and verification.

### Bug Report: [Short, descriptive title]

**Description:**
A clear and concise description of what the bug is. For example, "Users are redirected to the dashboard instead of their profile page after changing their email address."

**File Path Hints:**

-   `src/app/controllers/userController.js` (handles profile updates)
-   `src/app/views/profile.html` (the user profile page)

**Steps to Reproduce:**

1.  Log in as a user.
2.  Navigate to the `/profile` page.
3.  Click "Edit Email."
4.  Enter a new email and save.
5.  Observe the incorrect redirect to `/dashboard`.

**Acceptance Criteria:**

-   After a user successfully changes their email, they are redirected back to the `/profile` page.
-   A success message, "Your email has been updated," is displayed.

**Exit Criteria:**

-   All existing tests in the `tests/` directory must pass.
-   The new behavior is confirmed by the reproduction steps.

Purpose: To improve the internal structure of code without changing its external behavior. The focus is on specific code blocks and measurable improvements.

### Refactor Request: [Component or function to be refactored]

**Description:**
The `calculateBillingSummary` function in `src/services/billing.js` has grown too complex (over 100 lines) and is difficult to maintain. Refactor it into smaller, single-responsibility functions.

**File Path Hints:**

-   `src/services/billing.js`

**Refactor Goals:**

-   Extract the logic for calculating taxes into a separate `calculateTax(subtotal)` function.
-   Extract the logic for applying discounts into a `applyDiscounts(items)` function.
-   The main `calculateBillingSummary` function should orchestrate calls to these new functions.
-   No external behavior should change; the final output must be identical.

**Acceptance Criteria:**

-   The `calculateBillingSummary` function is now less than 40 lines of code.
-   New private helper functions (`_calculateTax`, `_applyDiscounts`) are created within the same file.

**Exit Criteria:**

-   All tests in `tests/services/billing.test.js` must continue to pass without modification to the tests themselves.

Purpose: To safely update an outdated package. This template emphasizes verification and regression testing.

### Dependency Bump: [Package Name]

**Description:**
Update the `requests` library from version `2.25.1` to the latest stable version (`2.28.1`). This is required to patch a security vulnerability.

**File Path Hints:**

-   `package.json`
-   `yarn.lock` or `package-lock.json`

**Tasks:**

1.  Identify the target version for the `requests` package.
2.  Update the version in `package.json`.
3.  Run the package manager's install command to update the lock file.
4.  Search the codebase for any usages of the package to check for breaking changes mentioned in the changelog.

**Acceptance Criteria:**

-   The `requests` package is updated to `2.28.1` in the lock file.
-   The application builds and starts successfully.

**Exit Criteria:**

-   All integration tests that rely on HTTP requests must pass.

Purpose: To correct or improve documentation. This is often a pure text-based task, ideal for an AI agent.

### Doc Fix: [Section or topic to improve]

**Description:**
The "Getting Started" guide in `docs/getting-started.md` has an outdated code sample for initializing the SDK. It needs to be updated to reflect the new `initializeKinde()` method.

**File Path Hints:**

-   `docs/getting-started.md`

**Required Changes:**

-   In the "Initialization" section, replace the old code block:
    ```javascript
    // Old code
    const kinde = new Kinde("YOUR_CLIENT_ID");
    ```

• With the new code block:

  // New code
  import {initializeKinde} from "@kinde/sdk";
  const kinde = initializeKinde("YOUR_CLIENT_ID", "YOUR_DOMAIN");
  

Acceptance Criteria:

• The specified code block in docs/getting-started.md is updated.
• The surrounding text and formatting remain unchanged.

Exit Criteria:

• A manual review of the updated Markdown file confirms the change is correct.

---

### 5. Test Addition Template

**Purpose:** To increase test coverage for a specific piece of functionality. This requires the agent to understand the code and write new, validating tests.

```markdown
### Test Addition: [Function or component to test]

**Description:**
The `getUserPermissions` function in `src/utils/permissions.js` lacks unit test coverage. Add tests to cover its main logic, including the case where a user has no assigned roles.

**File Path Hints:**
*   `src/utils/permissions.js` (the function to test)
*   `tests/utils/permissions.test.js` (where to add the new tests)

**Scenarios to Cover:**
1.  A user with a single role ('admin') returns the correct permissions array.
2.  A user with multiple roles returns a combined, unique list of permissions.
3.  A user with no roles returns an empty array.
4.  A user that is `null` or `undefined` throws an error.

**Acceptance Criteria:**
- At least three new test cases are added to `tests/utils/permissions.test.js`.
- The new tests follow the existing testing patterns (e.g., using Jest).

**Exit Criteria:**
- Run the full test suite; all tests, including the new ones, must pass.
- Code coverage for `src/utils/permissions.js` increases.

Structuring work for AI agents often involves tasks related to core application functionalities like authentication, user management, and permissions. An agent might be tasked with adding a new API endpoint, securing it, and then enabling a feature flag for it.

Kinde provides robust APIs and clear documentation that make these tasks easier to script and delegate. For example, you could write an issue template for an AI agent to “Create a new protected API endpoint.” The agent’s instructions could point to Kinde’s documentation for registering a new API and managing its access.

This synergy is powerful. By using Kinde, you standardize how your application handles identity and access, which in turn simplifies the instructions you need to give an AI agent to build on top of it. The agent doesn’t need to understand the complexities of OAuth 2.0; it just needs to know how to use the Kinde Management API. This makes your agent-ready templates simpler and the agent’s job easier.

• Register and manage APIs
• Manage feature flags through the Kinde API