What is the difference between tasks.md and AGENTS.md?
AGENTS.md holds rules that are always true for the repository. tasks.md is a plan for one feature, used while that feature is being built and then archived or deleted.
Break a feature into a checklist a coding agent works through one task at a time: numbered tasks and sub-tasks tied to requirements, the commands that verify each step, and the rules for working the list. Start from one of 16 real plans.
# Tasks: My feature
Describe what is true for users when this feature is done.
## Tasks
- [ ] 1. Add the first task here, one small step an agent can finish and verify.
## Definition of done
- Every test passes, including the new ones.
- Every new behavior and every fixed bug has a test.
- Lint and type-check report no errors.
## How to work through this list
- Work on one task at a time, in order. Do not start the next task until the current one is done.
- When a task is done, change its "- [ ]" to "- [x]" in this file.
- Run the verification commands after each task and fix failures before moving on.
- If a task is blocked, unclear or bigger than described, stop and ask instead of improvising.
- Do not start work that is not in this list. Add it under a new task and ask first.
Commit the file next to the code it plans. Agents tick each box as they finish a task, so the file doubles as a progress report.
Sixteen plans for features teams build all the time, each with requirements, small verifiable tasks and a definition of done. Load one into the form and change the details for your project, or copy it as it is.
Sign-up, sign-in, sign-out and password reset with hashed passwords, rate limiting and session cookies.
Preconfigured for: Web apps adding their own authentication (Node, Python or Ruby back ends).
tasks.md# Tasks: Email and password sign-in
Users can create an account, sign in, sign out and reset a forgotten password. Passwords are never stored or logged in plain text.
## Requirements
1. Users sign up with an email and a password of at least 12 characters.
2. Passwords are hashed with argon2id or bcrypt; plain passwords never reach the database or logs.
3. Sign-in sets an HttpOnly, Secure, SameSite=Lax session cookie.
4. Repeated failed sign-ins are rate limited per account and per IP.
5. Users can reset a password through a single-use link that expires in 30 minutes.
## Tasks
- [ ] 1. Add the users table with a unique email and a password_hash column
- _Requirements: 1, 2_
- [ ] 1.1 Write the migration and its down migration
- [ ] 2. Implement password hashing and verification in one module
- _Requirements: 2_
- [ ] 2.1 Unit test that the stored value never equals the password
- [ ] 3. Build the sign-up endpoint and form with validation
- _Requirements: 1_
- [ ] 4. Build sign-in and sign-out with the session cookie
- _Requirements: 3_
- [ ] 5. Add rate limiting to sign-in
- _Requirements: 4_
- [ ] 5.1 Test that the 6th failed attempt in 15 minutes is refused
- [ ] 6. Build the password reset request and reset pages
- _Requirements: 5_
- [ ] 6.1 Store only a hash of the reset token; expire it after one use or 30 minutes
- [ ] 7. Write end-to-end tests for sign-up, sign-in, sign-out and reset
- _Requirements: 1, 3, 5_
## Verification
Run these from the repository root after each task:
- `npm test`
- `npm run lint`
- `npx tsc --noEmit`
## Definition of done
- Every test passes, including the new ones.
- Every new behavior and every fixed bug has a test.
- Lint and type-check report no errors.
- The README, API docs and changelog describe the change.
- No TODO, FIXME, debug logging or commented-out code is left from this work.
## Out of scope
- Social login and single sign-on.
- Two-factor authentication (planned separately).
## How to work through this list
- Work on one task at a time, in order. Do not start the next task until the current one is done.
- When a task is done, change its "- [ ]" to "- [x]" in this file.
- Run the verification commands after each task and fix failures before moving on.
- Make one commit per task, with the task number in the message.
- If a task is blocked, unclear or bigger than described, stop and ask instead of improvising.
- Do not start work that is not in this list. Add it under a new task and ask first.
OAuth 2.0 authorization-code login with PKCE and state checks, account linking by verified email, and tests with a mocked provider.
Preconfigured for: Apps adding social login next to existing accounts.
tasks.md# Tasks: OAuth login with Google and GitHub
Users can sign in with Google or GitHub. Existing accounts are linked only through a verified email address.
## Requirements
1. Use the authorization code flow with PKCE and a state parameter.
2. Client secrets are read from environment variables, never committed.
3. An OAuth identity links to an existing account only when the provider reports the email as verified.
4. Users can disconnect a provider if they still have another way to sign in.
## Tasks
- [ ] 1. Register OAuth apps for local development and document the callback URLs
- _Requirements: 2_
- [ ] 2. Add an identities table (provider, provider_user_id, user_id) with a unique key
- _Requirements: 3_
- [ ] 3. Implement the authorize redirect with PKCE and state
- _Requirements: 1_
- [ ] 4. Implement the callback: verify state, exchange the code, fetch the profile
- _Requirements: 1_
- [ ] 4.1 Reject the callback when state is missing or does not match
- [ ] 5. Link or create the account using the verified email rule
- _Requirements: 3_
- [ ] 6. Add the connected accounts settings page with disconnect
- _Requirements: 4_
- [ ] 7. Test the full flow against a mocked provider
- _Requirements: 1, 3, 4_
## Verification
Run these from the repository root after each task:
- `npm test`
- `npm run lint`
- `npx tsc --noEmit`
## Definition of done
- Every test passes, including the new ones.
- Every new behavior and every fixed bug has a test.
- Lint and type-check report no errors.
- The README, API docs and changelog describe the change.
## Out of scope
- Enterprise SSO (SAML or OIDC per customer).
## How to work through this list
- Work on one task at a time, in order. Do not start the next task until the current one is done.
- When a task is done, change its "- [ ]" to "- [x]" in this file.
- Run the verification commands after each task and fix failures before moving on.
- Make one commit per task, with the task number in the message.
- If a task is blocked, unclear or bigger than described, stop and ask instead of improvising.
- Do not start work that is not in this list. Add it under a new task and ask first.
One resource end to end: validated input, authorization, standard errors, pagination, tests and API docs.
Preconfigured for: Back-end services in Express, Fastify, FastAPI, Django REST or Rails.
tasks.md# Tasks: Projects API
Clients can list, create, read, update and delete their own projects through /api/projects.
## Requirements
1. Every route requires an authenticated user and only returns that user's projects.
2. Input is validated; unknown fields are rejected with 400.
3. Errors use the standard error shape with 400, 401, 403, 404 and 409 as they apply.
4. The list endpoint is paginated with a cursor and a maximum page size of 100.
## Tasks
- [ ] 1. Define the request and response schemas
- _Requirements: 2_
- [ ] 2. Add the projects table and model scoped by owner
- _Requirements: 1_
- [ ] 3. Implement GET /api/projects with cursor pagination
- _Requirements: 1, 4_
- [ ] 4. Implement POST, GET by id, PATCH and DELETE
- _Requirements: 1, 2, 3_
- [ ] 4.1 Return 404, not 403, for projects owned by someone else
- [ ] 5. Write tests for success, validation, unauthorized and another user's project
- _Requirements: 1, 2, 3_
- [ ] 6. Update the OpenAPI document
- _Requirements: 2, 3_
## Verification
Run these from the repository root after each task:
- `npm test`
- `npm run lint`
- `npx tsc --noEmit`
## Definition of done
- Every test passes, including the new ones.
- Every new behavior and every fixed bug has a test.
- Lint and type-check report no errors.
- The README, API docs and changelog describe the change.
## How to work through this list
- Work on one task at a time, in order. Do not start the next task until the current one is done.
- When a task is done, change its "- [ ]" to "- [x]" in this file.
- Run the verification commands after each task and fix failures before moving on.
- Make one commit per task, with the task number in the message.
- If a task is blocked, unclear or bigger than described, stop and ask instead of improvising.
- Do not start work that is not in this list. Add it under a new task and ask first.
A dark theme driven by design tokens, following the system setting with a manual override that persists, with contrast checked.
Preconfigured for: Web apps that already use CSS custom properties or Tailwind.
tasks.md# Tasks: Dark mode
The app has a dark theme that follows the system setting by default, with a manual light, dark or system choice that persists.
## Requirements
1. Every color comes from a semantic token; no hard-coded colors remain in components.
2. Default follows prefers-color-scheme; the user's choice overrides it and persists across visits.
3. No flash of the wrong theme on page load.
4. Text contrast is at least 4.5:1 in both themes.
## Tasks
- [ ] 1. Inventory hard-coded colors and replace them with semantic tokens
- _Requirements: 1_
- [ ] 2. Define dark values for every semantic token
- _Requirements: 1, 4_
- [ ] 3. Add the theme switch (light, dark, system) to settings
- _Requirements: 2_
- [ ] 4. Set the theme attribute in a small inline script before first paint
- _Requirements: 3_
- [ ] 5. Check contrast of text, borders and focus rings in both themes
- _Requirements: 4_
- [ ] 5.1 Fix any pair below 4.5:1 for text or 3:1 for UI parts
- [ ] 6. Add visual regression screenshots for both themes
- _Requirements: 1_
## Verification
Run these from the repository root after each task:
- `npm test`
- `npm run lint`
## Definition of done
- Every test passes, including the new ones.
- Lint and type-check report no errors.
- No TODO, FIXME, debug logging or commented-out code is left from this work.
- New UI works with the keyboard alone and passes the project accessibility checks.
## How to work through this list
- Work on one task at a time, in order. Do not start the next task until the current one is done.
- When a task is done, change its "- [ ]" to "- [x]" in this file.
- Run the verification commands after each task and fix failures before moving on.
- Make one commit per task, with the task number in the message.
- If a task is blocked, unclear or bigger than described, stop and ask instead of improvising.
- Do not start work that is not in this list. Add it under a new task and ask first.
Incremental migration with allowJs, strict mode switched on per folder, and no behavior changes along the way.
Preconfigured for: Node or front-end codebases moving to TypeScript.
tasks.md# Tasks: Migrate to TypeScript
All source files are TypeScript with strict mode on, and behavior is unchanged.
## Requirements
1. The build and tests stay green after every step.
2. No behavior changes are mixed into the migration.
3. The final config has strict true and no use of any without a comment explaining why.
## Tasks
- [ ] 1. Add TypeScript with allowJs and checkJs off, and a typecheck script
- _Requirements: 1_
- [ ] 2. Convert shared utilities and types first
- _Requirements: 1, 2_
- [ ] 2.1 Rename one folder per commit and fix the type errors it raises
- [ ] 3. Convert the data layer
- _Requirements: 1, 2_
- [ ] 4. Convert the UI or route handlers
- _Requirements: 1, 2_
- [ ] 5. Turn on strict and fix the remaining errors folder by folder
- _Requirements: 3_
- [ ] 6. Remove allowJs and delete leftover JSDoc type hacks
- _Requirements: 3_
## Verification
Run these from the repository root after each task:
- `npm test`
- `npx tsc --noEmit`
- `npm run build`
## Definition of done
- Every test passes, including the new ones.
- Lint and type-check report no errors.
- No TODO, FIXME, debug logging or commented-out code is left from this work.
## Out of scope
- Refactors or renames that are not needed to type the code.
## How to work through this list
- Work on one task at a time, in order. Do not start the next task until the current one is done.
- When a task is done, change its "- [ ]" to "- [x]" in this file.
- Run the verification commands after each task and fix failures before moving on.
- Make one commit per task, with the task number in the message.
- If a task is blocked, unclear or bigger than described, stop and ask instead of improvising.
- Do not start work that is not in this list. Add it under a new task and ask first.
- If the plan turns out to be wrong, update this file first, then the code.
A major-version upgrade done in steps: read the migration guide, apply codemods, fix deprecations, verify behavior.
Preconfigured for: Next.js, React, Django, Rails, Laravel or Angular major upgrades.
tasks.md# Tasks: Framework major upgrade
The app runs on the new major version of the framework with all tests passing and no deprecation warnings.
## Requirements
1. Every breaking change in the official migration guide is checked against the code.
2. The upgrade lands in small commits, each with a green build.
3. No unrelated dependency upgrades are mixed in.
## Tasks
- [ ] 1. List the breaking changes from the official migration guide that apply to this code
- _Requirements: 1_
- [ ] 2. Upgrade the framework and its first-party packages only, with the package manager
- _Requirements: 3_
- [ ] 3. Run the official codemods and review every change they make
- _Requirements: 1_
- [ ] 4. Fix the remaining breaking changes one area at a time
- _Requirements: 1, 2_
- [ ] 5. Remove deprecation warnings from the test and dev output
- _Requirements: 1_
- [ ] 6. Smoke test the main user flows in a production build
- _Requirements: 2_
## Verification
Run these from the repository root after each task:
- `npm test`
- `npm run lint`
- `npm run build`
## Definition of done
- Every test passes, including the new ones.
- Lint and type-check report no errors.
- The README, API docs and changelog describe the change.
- The branch is pushed and a pull request describes the change and how to test it.
## How to work through this list
- Work on one task at a time, in order. Do not start the next task until the current one is done.
- When a task is done, change its "- [ ]" to "- [x]" in this file.
- Run the verification commands after each task and fix failures before moving on.
- Make one commit per task, with the task number in the message.
- If a task is blocked, unclear or bigger than described, stop and ask instead of improvising.
- Do not start work that is not in this list. Add it under a new task and ask first.
GitHub Actions running lint, type-check, tests and build on every pull request, with caching and required checks.
Preconfigured for: Repositories with no CI or a flaky one.
tasks.md# Tasks: CI pipeline
Every pull request runs lint, type-check, tests and a production build, and cannot merge until they pass.
## Requirements
1. CI runs on every pull request and on pushes to main.
2. Dependencies are installed from the lockfile and cached.
3. The workflow uses no long-lived secrets for the checks.
4. The checks are required for merging into main.
## Tasks
- [ ] 1. Add .github/workflows/ci.yml with install, lint, type-check, test and build steps
- _Requirements: 1, 2_
- [ ] 1.1 Use the lockfile install command (npm ci, pnpm install --frozen-lockfile)
- [ ] 2. Enable dependency caching for the package manager
- _Requirements: 2_
- [ ] 3. Set minimal permissions (contents: read) on the workflow
- _Requirements: 3_
- [ ] 4. Make the test job fail on the first error and upload the test report
- _Requirements: 1_
- [ ] 5. Document how to mark the checks as required in branch protection
- _Requirements: 4_
## Verification
Run these from the repository root after each task:
- `npm test`
- `npm run lint`
- `npm run build`
## Definition of done
- Every test passes, including the new ones.
- The README, API docs and changelog describe the change.
- The branch is pushed and a pull request describes the change and how to test it.
## How to work through this list
- Work on one task at a time, in order. Do not start the next task until the current one is done.
- When a task is done, change its "- [ ]" to "- [x]" in this file.
- Run the verification commands after each task and fix failures before moving on.
- Make one commit per task, with the task number in the message.
- If a task is blocked, unclear or bigger than described, stop and ask instead of improvising.
- Do not start work that is not in this list. Add it under a new task and ask first.
Extracts UI strings into message files, adds locale detection and switching, and formats dates and numbers per locale.
Preconfigured for: Apps preparing for a second language.
tasks.md# Tasks: Internationalization
All user-facing text comes from message files, and the app can be switched between English and Spanish.
## Requirements
1. No user-facing string is hard-coded in components.
2. The locale comes from the user setting, then the browser, then English.
3. Dates, numbers and currency amounts are formatted with Intl for the active locale; amounts stay in USD.
4. Missing translations fall back to English and are reported in development.
## Tasks
- [ ] 1. Choose the i18n library and add English message files
- _Requirements: 1_
- [ ] 2. Extract strings screen by screen into message keys
- _Requirements: 1_
- [ ] 2.1 One screen per commit; keep keys grouped by screen
- [ ] 3. Add locale detection and a language switcher
- _Requirements: 2_
- [ ] 4. Replace manual date and number formatting with Intl
- _Requirements: 3_
- [ ] 5. Add the Spanish message file and the missing-key warning
- _Requirements: 4_
- [ ] 6. Add a test that fails on hard-coded strings in components
- _Requirements: 1_
## Verification
Run these from the repository root after each task:
- `npm test`
- `npm run lint`
## Definition of done
- Every test passes, including the new ones.
- Every new behavior and every fixed bug has a test.
- Lint and type-check report no errors.
- The README, API docs and changelog describe the change.
## Out of scope
- Right-to-left layouts.
- Translating marketing pages.
## How to work through this list
- Work on one task at a time, in order. Do not start the next task until the current one is done.
- When a task is done, change its "- [ ]" to "- [x]" in this file.
- Run the verification commands after each task and fix failures before moving on.
- Make one commit per task, with the task number in the message.
- If a task is blocked, unclear or bigger than described, stop and ask instead of improvising.
- Do not start work that is not in this list. Add it under a new task and ask first.
Measure first, then fix the biggest wins: bundle size, images, slow queries and N+1s, with before and after numbers.
Preconfigured for: Web apps with slow pages or failing Core Web Vitals.
tasks.md# Tasks: Performance pass
The three slowest pages load at least 30 percent faster, measured the same way before and after.
## Requirements
1. Every change is justified by a measurement taken before it.
2. Before and after numbers are recorded in the pull request.
3. No change trades correctness for speed.
## Tasks
- [ ] 1. Measure the three slowest pages with a production build and record the numbers
- _Requirements: 1, 2_
- [ ] 2. Find and fix N+1 queries and missing indexes on those pages
- _Requirements: 1, 3_
- [ ] 3. Reduce the JavaScript bundle: split routes and remove unused dependencies
- _Requirements: 1_
- [ ] 4. Serve images in modern formats with width and height set
- _Requirements: 1_
- [ ] 5. Remove render-blocking requests from first load
- _Requirements: 1_
- [ ] 6. Measure again the same way and record the results
- _Requirements: 2_
## Verification
Run these from the repository root after each task:
- `npm test`
- `npm run build`
## Definition of done
- Every test passes, including the new ones.
- The branch is pushed and a pull request describes the change and how to test it.
## How to work through this list
- Work on one task at a time, in order. Do not start the next task until the current one is done.
- When a task is done, change its "- [ ]" to "- [x]" in this file.
- Run the verification commands after each task and fix failures before moving on.
- Make one commit per task, with the task number in the message.
- If a task is blocked, unclear or bigger than described, stop and ask instead of improvising.
- Do not start work that is not in this list. Add it under a new task and ask first.
- If the plan turns out to be wrong, update this file first, then the code.
Fixes the issues from an accessibility audit in priority order: keyboard, names, contrast, forms, then automated checks in CI.
Preconfigured for: Teams responding to a WCAG 2.2 AA audit.
tasks.md# Tasks: Accessibility remediation
The issues from the accessibility audit are fixed and automated checks stop new ones from shipping.
## Requirements
1. Every interactive element works with the keyboard alone, in a logical order.
2. Every control has an accessible name.
3. Text contrast is at least 4.5:1 and UI part contrast at least 3:1.
4. Form errors are announced and tied to their fields.
5. Automated accessibility checks run in CI.
## Tasks
- [ ] 1. Replace clickable div and span elements with buttons and links
- _Requirements: 1, 2_
- [ ] 2. Fix focus order and add visible focus styles
- _Requirements: 1_
- [ ] 3. Add accessible names to icon buttons and inputs
- _Requirements: 2_
- [ ] 4. Fix color pairs below the contrast minimums
- _Requirements: 3_
- [ ] 5. Connect form errors with aria-describedby and announce them
- _Requirements: 4_
- [ ] 6. Add automated accessibility checks to the component and e2e tests
- _Requirements: 5_
## Verification
Run these from the repository root after each task:
- `npm test`
- `npm run lint`
## Definition of done
- Every test passes, including the new ones.
- Every new behavior and every fixed bug has a test.
- New UI works with the keyboard alone and passes the project accessibility checks.
## Out of scope
- A redesign: fix the existing components in place.
## How to work through this list
- Work on one task at a time, in order. Do not start the next task until the current one is done.
- When a task is done, change its "- [ ]" to "- [x]" in this file.
- Run the verification commands after each task and fix failures before moving on.
- Make one commit per task, with the task number in the message.
- If a task is blocked, unclear or bigger than described, stop and ask instead of improvising.
- Do not start work that is not in this list. Add it under a new task and ask first.
One-time payments with hosted Stripe Checkout in USD, webhook fulfillment with signature checks, and test-mode only.
Preconfigured for: Apps selling a product or plan for the first time.
tasks.md# Tasks: Stripe Checkout
Customers can pay for a plan through Stripe Checkout in US dollars, and orders are fulfilled from the webhook, not the redirect.
## Requirements
1. Prices are defined in Stripe in USD and referenced by price ID, never sent from the browser.
2. Fulfillment happens only in the webhook after the signature is verified.
3. Webhook handling is idempotent: a repeated event never fulfills twice.
4. All development and tests use test-mode keys from environment variables.
## Tasks
- [ ] 1. Create the products and USD prices in test mode and store the price IDs in config
- _Requirements: 1, 4_
- [ ] 2. Add the endpoint that creates a Checkout Session for a price ID
- _Requirements: 1_
- [ ] 3. Add the success and cancel pages; show status only, do not fulfill
- _Requirements: 2_
- [ ] 4. Add the webhook endpoint with signature verification
- _Requirements: 2_
- [ ] 4.1 Handle checkout.session.completed and record the event ID
- [ ] 5. Make fulfillment idempotent on the event ID
- _Requirements: 3_
- [ ] 6. Test with the Stripe CLI forwarding test events
- _Requirements: 2, 3, 4_
## Verification
Run these from the repository root after each task:
- `npm test`
- `npm run lint`
- `npx tsc --noEmit`
## Definition of done
- Every test passes, including the new ones.
- Every new behavior and every fixed bug has a test.
- Lint and type-check report no errors.
- The README, API docs and changelog describe the change.
- The change ships behind a feature flag that is off by default.
## Out of scope
- Subscriptions and proration.
- Currencies other than USD.
## How to work through this list
- Work on one task at a time, in order. Do not start the next task until the current one is done.
- When a task is done, change its "- [ ]" to "- [x]" in this file.
- Run the verification commands after each task and fix failures before moving on.
- Make one commit per task, with the task number in the message.
- If a task is blocked, unclear or bigger than described, stop and ask instead of improvising.
- Do not start work that is not in this list. Add it under a new task and ask first.
Postgres full-text search with a generated tsvector column, a GIN index, ranked results and a debounced search box.
Preconfigured for: Apps on PostgreSQL adding search without a separate service.
tasks.md# Tasks: Full-text search
Users can search articles by title and body, with ranked results in under 200 ms for the current data size.
## Requirements
1. Search covers title and body, with the title weighted higher.
2. Queries use an index; no sequential scan on the articles table.
3. Users only see results they are allowed to read.
4. The search box is debounced and accessible.
## Tasks
- [ ] 1. Add a generated tsvector column with title weighted A and body B
- _Requirements: 1_
- [ ] 2. Add a GIN index on it, created concurrently
- _Requirements: 2_
- [ ] 3. Implement the search query with websearch_to_tsquery and ts_rank
- _Requirements: 1, 2_
- [ ] 3.1 Confirm with EXPLAIN that the index is used
- [ ] 4. Apply the existing permission filter to search results
- _Requirements: 3_
- [ ] 5. Build the search box with a 250 ms debounce and a results list
- _Requirements: 4_
- [ ] 6. Test ranking, permissions and empty queries
- _Requirements: 1, 3_
## Verification
Run these from the repository root after each task:
- `npm test`
- `npm run lint`
- `npx tsc --noEmit`
## Definition of done
- Every test passes, including the new ones.
- Every new behavior and every fixed bug has a test.
- Lint and type-check report no errors.
- New UI works with the keyboard alone and passes the project accessibility checks.
## How to work through this list
- Work on one task at a time, in order. Do not start the next task until the current one is done.
- When a task is done, change its "- [ ]" to "- [x]" in this file.
- Run the verification commands after each task and fix failures before moving on.
- Make one commit per task, with the task number in the message.
- If a task is blocked, unclear or bigger than described, stop and ask instead of improvising.
- Do not start work that is not in this list. Add it under a new task and ask first.
Direct-to-S3 uploads with presigned URLs, type and size limits, private storage and short-lived download links.
Preconfigured for: Apps adding avatars, attachments or document uploads.
tasks.md# Tasks: File uploads
Users can upload attachments up to 10 MB directly to private S3 storage and download them through short-lived links.
## Requirements
1. Uploads go straight from the browser to S3 with a presigned URL; the app server never proxies the file.
2. Only allowed file types up to 10 MB are accepted, checked on the server before presigning.
3. The bucket is private; downloads use presigned links that expire in 5 minutes.
4. Object keys are random and never contain the original file name or user data.
## Tasks
- [ ] 1. Create the private bucket policy and CORS rule for the app origin
- _Requirements: 1, 3_
- [ ] 2. Add the endpoint that validates type and size and returns a presigned POST
- _Requirements: 1, 2_
- [ ] 2.1 Generate a random object key per upload
- [ ] 3. Record the upload in the attachments table after the client confirms
- _Requirements: 4_
- [ ] 4. Add the download endpoint returning a 5 minute presigned GET
- _Requirements: 3_
- [ ] 5. Build the upload component with progress and error states
- _Requirements: 1_
- [ ] 6. Test rejection of wrong types, oversize files and other users' attachments
- _Requirements: 2, 3_
## Verification
Run these from the repository root after each task:
- `npm test`
- `npm run lint`
- `npx tsc --noEmit`
## Definition of done
- Every test passes, including the new ones.
- Every new behavior and every fixed bug has a test.
- Lint and type-check report no errors.
- The README, API docs and changelog describe the change.
## Out of scope
- Virus scanning (planned separately).
- Image resizing.
## How to work through this list
- Work on one task at a time, in order. Do not start the next task until the current one is done.
- When a task is done, change its "- [ ]" to "- [x]" in this file.
- Run the verification commands after each task and fix failures before moving on.
- Make one commit per task, with the task number in the message.
- If a task is blocked, unclear or bigger than described, stop and ask instead of improvising.
- Do not start work that is not in this list. Add it under a new task and ask first.
Sets up a test runner, CI-ready scripts and the first tests where they protect the most: money, auth and data writes.
Preconfigured for: Codebases with no tests yet.
tasks.md# Tasks: Test suite from zero
The project has a working test runner, a test script in CI, and tests covering the riskiest code paths.
## Requirements
1. One command runs all tests locally and in CI.
2. The first tests cover the code that handles money, authentication and data writes.
3. Tests do not depend on network access or real external services.
## Tasks
- [ ] 1. Add the test runner and a test script that runs everything
- _Requirements: 1_
- [ ] 2. Add one passing smoke test to prove the setup
- _Requirements: 1_
- [ ] 3. List the riskiest modules: money, auth, data writes
- _Requirements: 2_
- [ ] 4. Write characterization tests for each listed module
- _Requirements: 2_
- [ ] 4.1 Pin current behavior, including odd behavior; report bugs separately
- [ ] 5. Mock external services at the network boundary
- _Requirements: 3_
- [ ] 6. Run the tests in CI on every pull request
- _Requirements: 1_
## Verification
Run these from the repository root after each task:
- `npm test`
## Definition of done
- Every test passes, including the new ones.
- The README, API docs and changelog describe the change.
## How to work through this list
- Work on one task at a time, in order. Do not start the next task until the current one is done.
- When a task is done, change its "- [ ]" to "- [x]" in this file.
- Run the verification commands after each task and fix failures before moving on.
- Make one commit per task, with the task number in the message.
- If a task is blocked, unclear or bigger than described, stop and ask instead of improvising.
- Do not start work that is not in this list. Add it under a new task and ask first.
Ships a change behind a flag: off by default, enabled for staff, then a percentage, with a tested kill switch and cleanup.
Preconfigured for: Teams releasing risky changes gradually.
tasks.md# Tasks: Feature flag rollout
The new checkout flow reaches all users gradually, can be turned off instantly, and the flag is removed once it is fully on.
## Requirements
1. The flag is off by default in every environment.
2. The flag can enable the feature for staff, then for a percentage of users.
3. Turning the flag off restores the old flow immediately with no deploy.
4. The flag and the old code path are removed after full rollout.
## Tasks
- [ ] 1. Add the flag with a default of off
- _Requirements: 1_
- [ ] 2. Put the new flow behind the flag, keeping the old flow intact
- _Requirements: 1, 3_
- [ ] 3. Add targeting for staff accounts and a stable percentage rollout
- _Requirements: 2_
- [ ] 4. Test both paths and the switch between them
- _Requirements: 3_
- [ ] 5. Write the rollout plan: staff, 5, 25, 50, 100 percent with the metrics to watch
- _Requirements: 2_
- [ ] 6. After full rollout, remove the flag and the old path
- _Requirements: 4_
## Verification
Run these from the repository root after each task:
- `npm test`
- `npm run lint`
- `npx tsc --noEmit`
## Definition of done
- Every test passes, including the new ones.
- Every new behavior and every fixed bug has a test.
- The branch is pushed and a pull request describes the change and how to test it.
- The change ships behind a feature flag that is off by default.
## How to work through this list
- Work on one task at a time, in order. Do not start the next task until the current one is done.
- When a task is done, change its "- [ ]" to "- [x]" in this file.
- Run the verification commands after each task and fix failures before moving on.
- Make one commit per task, with the task number in the message.
- If a task is blocked, unclear or bigger than described, stop and ask instead of improvising.
- Do not start work that is not in this list. Add it under a new task and ask first.
A privacy request flow: users download their personal data and delete their account, with backups and processors covered.
Preconfigured for: Products serving users in the EU or anyone handling personal data.
tasks.md# Tasks: Data export and account deletion
Users can download a copy of their personal data and delete their account themselves, and both requests are handled completely and logged without personal data.
## Requirements
1. Users can request an export of all personal data held about them, delivered as JSON.
2. Users can delete their account after re-authenticating.
3. Deletion removes or anonymizes personal data in every table and in third-party processors.
4. Requests are logged with an opaque request ID, never with personal data.
5. Retention for backups is documented, and restored backups re-apply deletions.
## Tasks
- [ ] 1. Inventory every table and processor that stores personal data
- _Requirements: 1, 3_
- [ ] 1.1 Record the inventory in docs/privacy/data-map.md
- [ ] 2. Build the export job that collects the data into one JSON file
- _Requirements: 1_
- [ ] 3. Add the export download with a link that expires in 24 hours
- _Requirements: 1_
- [ ] 4. Build account deletion behind re-authentication
- _Requirements: 2_
- [ ] 5. Delete or anonymize data in each table and call each processor's deletion API
- _Requirements: 3_
- [ ] 6. Log both request types with an opaque ID only
- _Requirements: 4_
- [ ] 7. Record deleted account IDs so restored backups re-apply deletions
- _Requirements: 5_
- [ ] 8. Test with a synthetic user that both flows leave no personal data behind
- _Requirements: 1, 3_
## Verification
Run these from the repository root after each task:
- `npm test`
- `npm run lint`
- `npx tsc --noEmit`
## Definition of done
- Every test passes, including the new ones.
- Every new behavior and every fixed bug has a test.
- The README, API docs and changelog describe the change.
- The branch is pushed and a pull request describes the change and how to test it.
## Out of scope
- Deciding legal retention periods: confirm them with whoever owns privacy compliance.
## How to work through this list
- Work on one task at a time, in order. Do not start the next task until the current one is done.
- When a task is done, change its "- [ ]" to "- [x]" in this file.
- Run the verification commands after each task and fix failures before moving on.
- Make one commit per task, with the task number in the message.
- If a task is blocked, unclear or bigger than described, stop and ask instead of improvising.
- Do not start work that is not in this list. Add it under a new task and ask first.
- If the plan turns out to be wrong, update this file first, then the code.
A tasks.md file is a plan for one feature, written as a Markdown checklist. Each line is a task small enough to finish and verify in one sitting, numbered in the order it should be done, with sub-tasks underneath when a step has parts. Requirements sit at the top, numbered, and each task says which requirements it serves.
Agents do noticeably better with a plan than with a paragraph. Given "add sign-in", an agent will often write everything at once and hand back a large diff nobody can review. Given a list, it builds the table, then the hashing, then the endpoint, running the tests after each step and ticking the box. You can stop it, review progress, and resume, because the file records what is done.
The generator writes this structure, here with one task from the sign-in template:
# Tasks: Email and password sign-in
## Requirements
1. Users sign up with an email and a password of at least 12 characters.
2. Passwords are hashed with argon2id or bcrypt.
## Tasks
- [ ] 1. Add the users table with a unique email and a password_hash column
- _Requirements: 1, 2_
- [ ] 1.1 Write the migration and its down migrationThen come Verification (the commands to run after each task), Definition of done, Out of scope and How to work through this list. Every line is plain Markdown, so the checkboxes render on GitHub and GitLab and any agent can read and edit the file.
- to make it a sub-task of the task above it. Sub-tasks are numbered 1.1, 1.2 and so on.:: 1, 3 to tie it to requirements 1 and 3. A reference to a requirement that does not exist is left out, and a note tells you which one.The generator renumbers everything for you, so you can reorder lines freely.
Choose one of three locations. tasks.md at the root suits a single feature in flight. docs/plans/<feature>/tasks.md keeps a history of plans. .kiro/specs/<feature>/tasks.md is where Kiro keeps specs.
Kiro's documentation, read on 2026-11-14, says every spec has three files: requirements.md, design.md and tasks.md, where tasks.md is "a detailed implementation plan with discrete, trackable tasks". Kiro shows task status as you work and can run independent tasks in parallel. See Kiro specs. The exact checkbox and _Requirements:_ notation used here is the common convention for these files; the page we read did not spell it out, so check a spec Kiro generated in your own project if you rely on its task runner.
- [ ] to - [x], and commit with the task number in the message.These steps are the working rules you can tick in the form. They go into the file itself, so any agent you hand it to follows the same process.
Yes. The form, the generated plan and the templates all run in this page. Nothing you type is uploaded, stored or added to the address bar. The same answers always produce the same file.
AGENTS.md holds rules that are always true for the repository. tasks.md is a plan for one feature, used while that feature is being built and then archived or deleted.
Not for this generator: requirements are written into tasks.md itself. If you use Kiro specs, Kiro keeps requirements.md and design.md in the same folder as tasks.md.
Small enough to finish, verify and commit in one step, usually under an hour of human work. If a task needs several unrelated changes, split it into sub-tasks or separate tasks.
If you tick the working rule "Tick the box when done", the file tells it to. Most agents follow it when the file is in the conversation, and you can check progress by reading the file.
Yes. It is a plain Markdown checklist that renders on GitHub and GitLab, so it works as a human plan or a pull request checklist too.
You do not have to take our word for it. Developer tools show every request a page makes, so you can watch this page work and confirm that nothing you type is sent. The check takes under a minute.
F12, or Cmd+Option+I on a Mac, and select the Network tab.Only the feedback form can add a line to that log, and it sends only the vote and comment you type into it. 2prompt has no server code at all: no API, no model and no database of your files. The production site also sends a Content-Security-Policy header that tells your browser to refuse connections to anywhere except this site, the fonts and the anonymous analytics endpoint.