Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 5 additions & 2 deletions .agents/skills/get-started/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ Ask targeted questions interview-style, one question at a time, to find out what
- ... (any other question that helps you create an implementation plan and learn about the developer and the project)

## 2. Plan
Make a plan for the execution of the initial project. Be sure to keep the developer involved in writing the plan.
Make a plan for the execution of the initial project. Be sure to keep the developer involved in writing the plan.
Present the plan to the developer. Finally, save the plan in `docs/plans/active/YYYY-MM-DD-get-started.md`.
Keep open follow-up items in a `## TODOs` section at the bottom of that plan file using markdown checkboxes.

Expand All @@ -43,11 +43,14 @@ Handle template scaffolding based on the chosen project language:
- Move `templates/py/.pre-commit-config.yaml`, `templates/py/.gitignore`, and `templates/py/pyproject.toml` to the repo root.
- Delete `templates/ts/` and any TS-only template files.
- If the project is **TypeScript**:
- Move `templates/ts/package.json`, `templates/ts/.gitignore`, `templates/ts/tsconfig.json`, `templates/ts/eslint.config.mjs`, `templates/ts/secretlint.config.mjs`, and `templates/ts/.husky/` to the repo root.
- Move `templates/ts/package.json`, `templates/ts/.npmrc`, `templates/ts/pnpm-workspace.yaml`, `templates/ts/.gitignore`, `templates/ts/tsconfig.json`, `templates/ts/eslint.config.mjs`, `templates/ts/.secretlintrc.json`, `templates/ts/.prettierignore`, and `templates/ts/.husky/` to the repo root.
- Delete `templates/py/` and any Python-only template files.
- If the project is **neither Python nor TypeScript**:
- Create equivalent starter files for the selected stack in the repo root.
- Remove both `templates/py/` and `templates/ts/` so only relevant files remain.
- In `pyproject.toml` or `package.json`, set the project `name` and reset `version` to `0.1.0`. Replace `CHANGELOG.md` with an empty one for the new project.
- In `.github/workflows/validate.yml`, keep only the job for the chosen stack and adapt it to the project: run it from the repo root, remove the template-only steps and settings (the placeholder source file and the `SKIP: deptry` setting), and use `pnpm install --frozen-lockfile` once a lockfile exists. For other stacks, replace the jobs with ones that run the stack's checks.
- In `.github/dependabot.yml`, keep only the entry for the chosen stack and set its `directory` to `/`. For other stacks, replace the entries with one for the stack's package ecosystem.
Execute the plan. Make sure to keep the developer in the loop and explain what you are doing.
Before handoff, validate that the configured repo works:
- Run the smallest relevant install/setup command for the chosen stack.
Expand Down
48 changes: 48 additions & 0 deletions .github/workflows/validate.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
name: validate

on:
pull_request:
push:
branches: [main]

permissions:
contents: read

jobs:
python:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
with:
working-directory: templates/py
# deptry needs a [project] section, which only exists after get-started.
- run: uvx pre-commit@4.6.2 run --all-files --show-diff-on-failure --config templates/py/.pre-commit-config.yaml
env:
SKIP: deptry

typescript:
runs-on: ubuntu-latest
defaults:
run:
working-directory: templates/ts
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
with:
package_json_file: templates/ts/package.json
- uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
with:
node-version: 26
check-latest: true
- run: pnpm install
# The template has no source files; add one so tsc and knip have input.
- run: |
mkdir -p src
printf '/** Add two numbers. */\nexport function add(a: number, b: number): number {\n return a + b;\n}\n' > src/index.ts
- run: pnpm validate
- run: pnpm format:check
8 changes: 7 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,9 @@
- When installing or updating dependencies, verify before installation that the selected version has no known
supply-chain compromise reports or critical CVEs.
- Always pin dependencies to exact versions in manifests or lockfiles instead of using floating version ranges.
- Only exempt a package from the release-age delay (`exclude-newer-package`, `min-release-age-exclude`, `minimumReleaseAgeExclude`)
to install a security fix. Remove the exemption once the fixed version is older than the delay. Permanent settings
that have a comment saying so (for example the `certifi` delay in `pyproject.toml`) stay.
- Do not install anything known or suspected to be a security risk.
- Never hardcode secrets, API keys, passwords, or tokens in code. Use environment variables or secure vault services.
- Do not log or expose sensitive information like credentials, PII, or authentication tokens.
Expand All @@ -32,6 +35,7 @@

## Approach
- Check `docs/` for plans and their embedded TODO sections that are relevant to the current session.
- At the start of a session, check the temporary release-age exemptions. If an exempted fixed version is now older than the delay, remove the exemption.
- Do not rely on your internal knowledge about APIs, libraries, and tools. Assume that it might be outdated. Use web search and web fetch to retrieve relevant documentation.
- Implement the basic happy path of any functionality or feature first. Only after confirmation from the user, implement the edge cases.
- Only implement features and functionality that the user asked for.
Expand All @@ -48,6 +52,8 @@

## Documentation & Memory
- Avoid overdocumenting (e.g. README.md in every folder, excessive comments in the code).
- Keep `CHANGELOG.md` up to date. Record each user-visible change under the next version, in the same change that makes it.
When you release a version, update the version in `pyproject.toml` or `package.json` to match.
- Keep session-spanning plans in state-specific folders:
- `docs/plans/active/YYYY-MM-DD-{plan-name}.md` for plans currently being worked
- `docs/plans/pending/YYYY-MM-DD-{plan-name}.md` for approved plans that are not currently active
Expand All @@ -59,4 +65,4 @@
- [ ] pending todo
- [x] todo completed
- Do not remove completed TODOs from plan files; keep them for historical context.
- When searching through plans and decisions and past todos, use targeted keyword search rather than loading all the files into context.
- When searching through plans and decisions and past todos, use targeted keyword search rather than loading all the files into context.
54 changes: 54 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
# Changelog

All notable changes to this project are recorded in this file.
The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses [Semantic Versioning](https://semver.org/).

## [0.2.0] - 2026-10-27

Pull request: [#8](https://github.com/Kickstart-AI/agent-ready-template/pull/8)

This release protects the templates against recent vulnerabilities and supply-chain attacks. It blocks tool versions with known vulnerabilities, delays new package releases, and pins all dependencies.

### Security
- Require patched Node.js versions. See the [Node.js October 2026 security releases](https://nodejs.org/en/blog/vulnerability/october-2026-security-releases).
- Require a `uv` version that does not trust the compromised eMudhra/emSign CA certificates. See the [Python announcement on the eMudhra/emSign CA certificate incident](https://discuss.python.org/t/information-for-python-users-regarding-emudhra-emsign-ca-certificate-security-incident/109576).
- Exempt the patched `zod` 4.6.6 ([GHSA-mrhx-c7xc-m3w5](https://github.com/advisories/GHSA-mrhx-c7xc-m3w5)) and `fast-uri` 3.1.9 ([GHSA-w74x-v6f9-j3xg](https://github.com/advisories/GHSA-w74x-v6f9-j3xg)) from the 30-day release delay in the TypeScript template.
- Remove the `braces` vulnerability ([GHSA-vfj7-8cjw-p6xm](https://github.com/advisories/GHSA-vfj7-8cjw-p6xm)) from the TypeScript template tools.

### Added
- A GitHub workflow (`.github/workflows/validate.yml`) that runs the Python and TypeScript template checks.
- A version in `templates/py/pyproject.toml` and `templates/ts/package.json`, and this changelog.
- A 30-day release delay for npm (`.npmrc`) and pnpm (`pnpm-workspace.yaml`). This matches the `uv` delay.
- Minimum versions for Node.js (`engines.node`) and `uv` (`required-version`) that block releases with known vulnerabilities.
- An exemption from the `uv` release delay for `certifi`, so that certificate revocations install quickly.
- `get-started` steps that adapt the workflow, the Dependabot configuration, and the version to the new project.

### Changed
- The TypeScript template pins all direct dependencies and pnpm to exact versions.
- The TypeScript template uses the newest major versions of its tools that are at least 30 days old.
- The ESLint configuration uses `defineConfig` and does not use type-aware rules on `.mjs` files.
- `tsconfig.json` includes root `*.config.ts` files, so typed linting works for them.
- The Python template uses `pre-commit-hooks` v6.0.0.

### Fixed
- secretlint did not find its configuration. It now uses `.secretlintrc.json`.
- Knip, ESLint, and Prettier failed on a new TypeScript project.
- Missing final newlines and trailing whitespace in the agent instruction files.

### Removed
- The redundant `@typescript-eslint/parser` and `@typescript-eslint/eslint-plugin` packages. `typescript-eslint` supplies them.

## [0.1.0] - 2026-05-22

### Added
- Agent instructions (`AGENTS.md`, `CLAUDE.md`) with coding, security, communication, and documentation rules.
- The `get-started` and `wrap-up` agent skills.
- A documentation structure for plans, decisions, and TODOs.
- Python and TypeScript starter templates with linting, type checks, dead-code and duplicate-code detection, and secret scanning.
- A Dependabot configuration for the template dependencies, with a 30-day cooldown and grouped updates.

### Changed
- Dependency updates from Dependabot ([#6](https://github.com/Kickstart-AI/agent-ready-template/pull/6)).

[0.2.0]: https://github.com/Kickstart-AI/agent-ready-template/pull/8
[0.1.0]: https://github.com/Kickstart-AI/agent-ready-template/commits/main
2 changes: 1 addition & 1 deletion CLAUDE.md
Original file line number Diff line number Diff line change
@@ -1 +1 @@
@AGENTS.md
@AGENTS.md
9 changes: 6 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -85,17 +85,20 @@ It is inspired by the concept of "Agent Readiness" by Factory.AI: https://factor
- `.gitignore`
- `pyproject.toml`

Use this set for Python projects. It uses `uv`, `ruff`, `ty`, pre-commit checks, and secret scanning because they are fast, easy for agents to run locally. The `uv` config waits 30 days before accepting new package releases.
Use this set for Python projects. It uses `uv`, `ruff`, `ty`, pre-commit checks, and secret scanning because they are fast, easy for agents to run locally. The `uv` config waits 30 days before accepting new package releases and sets a minimum `uv` version (`required-version`) that blocks releases with known vulnerabilities. Raise it when `uv` publishes a security release. `certifi`, the CA certificate bundle, has a short permanent delay of 2 days instead, so certificate revocations install quickly. To let another urgent security fix through, add the package to `exclude-newer-package`.

#### `ts/`

- `package.json`
- `.npmrc`
- `pnpm-workspace.yaml`
- `.gitignore`
- `tsconfig.json`
- `eslint.config.mjs`
- `secretlint.config.mjs`
- `.secretlintrc.json`
- `.prettierignore`
- `.husky/pre-commit`
- `.husky/pre-push`
- `.husky/_/husky.sh`

Use this set for TypeScript projects. It uses Husky and lint-staged, while CI can still run the full validation script. ESLint, TypeScript, Knip, jscpd, and secretlint cover linting, strict typing, dead code, duplicate code, and secrets.
Use this set for TypeScript projects. It uses Husky and lint-staged, while CI can still run the full validation script. ESLint, TypeScript, Knip, jscpd, and secretlint cover linting, strict typing, dead code, duplicate code, and secrets. All direct dependencies, and pnpm itself, are pinned to exact versions. Both npm (`.npmrc`) and pnpm (`pnpm-workspace.yaml`) wait 30 days before accepting new package releases. To let an urgent security fix through, add the package to `min-release-age-exclude` in `.npmrc` and to `minimumReleaseAgeExclude` in `pnpm-workspace.yaml`. `package.json` sets a patched minimum version for each supported Node.js line (`engines.node`), and both package managers refuse to install on an older version. Raise these minimums when Node.js publishes a security release. In CI, set `check-latest: true` on `actions/setup-node`, because runner images can lag behind a security release.
2 changes: 1 addition & 1 deletion templates/py/.pre-commit-config.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ minimum_pre_commit_version: "4.0.0"
repos:
# Generic repository hygiene (includes large file detection).
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v5.0.0
rev: v6.0.0
hooks:
- id: check-added-large-files
args: ["--maxkb=500"]
Expand Down
8 changes: 8 additions & 0 deletions templates/py/pyproject.toml
Original file line number Diff line number Diff line change
@@ -1,3 +1,8 @@
[project]
name = "agent-ready-template"
version = "0.2.0"
requires-python = ">=3.11"

[tool.ruff]
line-length = 100
target-version = "py311"
Expand Down Expand Up @@ -31,4 +36,7 @@ exclude = [".venv", "venv", "build", "dist"]
respect-type-ignore-comments = true

[tool.uv]
required-version = ">=0.13.5"
exclude-newer = "30 days"
# certifi releases are trust-store fixes. Keep this short delay permanently.
exclude-newer-package = { certifi = "2 days" }
4 changes: 4 additions & 0 deletions templates/ts/.npmrc
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
engine-strict=true
min-release-age=30
min-release-age-exclude[]=zod
min-release-age-exclude[]=fast-uri
1 change: 1 addition & 0 deletions templates/ts/.prettierignore
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
pnpm-lock.yaml
3 changes: 3 additions & 0 deletions templates/ts/.secretlintrc.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
{
"rules": [{ "id": "@secretlint/secretlint-rule-preset-recommend" }]
}
48 changes: 30 additions & 18 deletions templates/ts/eslint.config.mjs
Original file line number Diff line number Diff line change
@@ -1,38 +1,50 @@
import js from "@eslint/js";
import { defineConfig } from "eslint/config";
import tseslint from "typescript-eslint";

export default tseslint.config(
export default defineConfig(
js.configs.recommended,
...tseslint.configs.strictTypeChecked,
...tseslint.configs.stylisticTypeChecked,
tseslint.configs.strictTypeChecked,
tseslint.configs.stylisticTypeChecked,
{
languageOptions: {
parserOptions: {
projectService: true,
tsconfigRootDir: import.meta.dirname
}
tsconfigRootDir: import.meta.dirname,
},
},
rules: {
"@typescript-eslint/consistent-type-imports": "error",
"@typescript-eslint/no-floating-promises": "error",
"@typescript-eslint/no-misused-promises": "error",
"complexity": ["error", 10],
"max-lines": ["error", { "max": 300, "skipBlankLines": true, "skipComments": true }],
"max-lines-per-function": ["error", { "max": 50, "skipBlankLines": true, "skipComments": true }],
complexity: ["error", 10],
"max-lines": [
"error",
{ max: 300, skipBlankLines: true, skipComments: true },
],
"max-lines-per-function": [
"error",
{ max: 50, skipBlankLines: true, skipComments: true },
],
"no-restricted-imports": [
"error",
{
"patterns": [
patterns: [
{
"group": ["**/internal/**", "**/_*/**"],
"message": "Import through the module's public boundary instead of private internals."
}
]
}
]
}
group: ["**/internal/**", "**/_*/**"],
message:
"Import through the module's public boundary instead of private internals.",
},
],
},
],
},
},
{
ignores: ["dist/**", "build/**", "coverage/**", "node_modules/**"]
}
files: ["**/*.mjs"],
extends: [tseslint.configs.disableTypeChecked],
},
{
ignores: ["dist/**", "build/**", "coverage/**", "node_modules/**"],
},
);
38 changes: 23 additions & 15 deletions templates/ts/package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,11 @@
{
"$schema": "https://json.schemastore.org/package.json",
"packageManager": "pnpm@10",
"name": "agent-ready-template",
"version": "0.2.0",
"packageManager": "pnpm@12.5.1",
"engines": {
"node": "^24.22.1 || >=26.12.1"
},
"scripts": {
"prepare": "husky",
"lint": "eslint . --max-warnings=0",
Expand All @@ -22,19 +27,22 @@
]
},
"devDependencies": {
"@eslint/js": "^10.0.1",
"@secretlint/secretlint-rule-preset-recommend": "^12.2.0",
"@types/node": "^25.6.0",
"@typescript-eslint/eslint-plugin": "^8.0.0",
"@typescript-eslint/parser": "^8.0.0",
"eslint": "^10.2.1",
"husky": "^9.0.0",
"jscpd": "^4.0.0",
"knip": "^6.6.1",
"lint-staged": "^16.0.0",
"prettier": "^3.0.0",
"secretlint": "^12.2.0",
"typescript-eslint": "^8.0.0",
"typescript": "^6.0.3"
"@eslint/js": "10.0.1",
"@secretlint/secretlint-rule-preset-recommend": "13.0.5",
"@types/node": "24.13.6",
"eslint": "10.11.0",
"husky": "9.1.7",
"jscpd": "5.3.1",
"knip": "6.37.0",
"lint-staged": "17.5.1",
"prettier": "3.9.8",
"secretlint": "13.0.5",
"typescript-eslint": "8.70.1",
"typescript": "6.0.3"
},
"knip": {
"ignoreDependencies": [
"@secretlint/secretlint-rule-preset-recommend"
]
}
}
5 changes: 5 additions & 0 deletions templates/ts/pnpm-workspace.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
minimumReleaseAge: 43200
Comment thread
jvdgoltz marked this conversation as resolved.
Resolved
savePrefix: ""
minimumReleaseAgeExclude:
- zod@4.6.6
- fast-uri@3.1.9
7 changes: 0 additions & 7 deletions templates/ts/secretlint.config.mjs

This file was deleted.

8 changes: 7 additions & 1 deletion templates/ts/tsconfig.json
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,12 @@
"strict": true,
"target": "ES2022"
},
"include": ["src/**/*.ts", "src/**/*.tsx", "tests/**/*.ts", "tests/**/*.tsx"],
"include": [
"src/**/*.ts",
"src/**/*.tsx",
"tests/**/*.ts",
"tests/**/*.tsx",
"*.config.ts"
],
"exclude": ["node_modules", "dist", "build", "coverage"]
}
Loading