jarlor · jarlor · May 2, 2026 · May 2, 2026 · May 2, 2026
diff --git a/.gitignore b/.gitignore
@@ -18,4 +18,4 @@ wheels/
 # OS/editor files
 .DS_Store
 .idea/
-AGENTS.md
+.agents/
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,39 @@
+# Agent Guide
+
+This repository is a vibecoding starter template. Keep it small, explicit, and easy for an AI coding agent to operate from a clean clone.
+
+## First Read
+
+- `README.md` for the project promise and common commands.
+- `docs/en/quickstart.md` for setup.
+- `docs/en/git-workflow.md` for branch, PR, release, and backmerge rules.
+- `docs/en/ci-cd.md` for workflow variables and deployment profiles.
+
+## Default Workflow
+
+- Work from short-lived branches.
+- Target `dev` for normal changes.
+- Target `main` only for release PRs or hotfixes.
+- Use Conventional Commit titles and commit messages.
+- Do not introduce a `test` branch; test/staging are environments.
+
+## Quality Bar
+
+Run before handing work back:
+
+```bash
+uv run poe check
+```
+
+If workflow or deploy scripts changed, also run:
+
+```bash
+bash -n scripts/cicd/*.sh scripts/init.sh scripts/pre-push.sh scripts/tag.sh
+```
+
+## Template Rules
+
+- Keep deployment opt-in. Do not make new clones require test or production hosts.
+- Keep release automation opt-in. `RELEASE_ENABLED=true` requires a working `RELEASE_TOKEN`.
+- Prefer clear docs over long docs; this template is a starting point, not a product manual.
+- Do not commit local environment files, generated caches, IDE files, or secrets.
diff --git a/README.md b/README.md
@@ -1,16 +1,17 @@
-# UV Python Repository Template
+# Vibecoding Python Starter
 
 [![Built with UV](https://img.shields.io/badge/built%20with-uv-7966C7)](https://github.com/astral-sh/uv)
 [![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-%23FE5196)](https://www.conventionalcommits.org)
 [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
 
 [中文文档](README_zh.md) | [Documentation](docs/)
 
-> A production-ready Python project template with uv, GitHub Actions, semantic release, and an opt-in deployment model for backend or full-stack projects.
+> A minimal Python starter for vibecoding: clean uv defaults, agent-facing instructions, strict Git workflow, CI governance, and opt-in deployment.
 
 ## What You Get
 
 - Fast setup with uv and a project rename initializer
+- `AGENTS.md` so AI coding agents know the repository rules immediately
 - `dev`/`main` Git model with PR and commit governance
 - CI for Python quality and optional frontend builds
 - Semantic-release changelog, tags, and GitHub Releases
@@ -66,22 +67,15 @@ All PR titles must follow Conventional Commit format. PRs into `main` must use a
 
 ## Workflow Profiles
 
-CI and governance are always on. Deployments are opt-in through GitHub Variables.
+CI and governance are always on. Deployments and release automation are opt-in through GitHub Variables.
 
 | Profile | Variables | Behavior |
 | --- | --- | --- |
-| `ci-only` | none | CI, PR governance, commit governance, semantic release only |
+| `ci-only` | none | CI, PR governance, and commit governance |
 | `prod-only` | `PROD_DEPLOY_ENABLED=true` | Deploy production after a released `main` build |
 | `test-and-prod` | `TEST_DEPLOY_ENABLED=true`, `PROD_DEPLOY_ENABLED=true` | Deploy test from `dev`, production from released `main` |
 
-Common deployment variables:
-
-| Environment | Secrets | Variables |
-| --- | --- | --- |
-| Test | `TEST_SSH_HOST`, `TEST_SSH_USER`, `TEST_SSH_KEY` | `TEST_DEPLOY_ENABLED`, `TEST_DEPLOY_PATH`, `TEST_SYSTEMD_SERVICE`, `TEST_HEALTH_URL`, `TEST_REPOSITORY_URL` |
-| Production | `PROD_SSH_HOST`, `PROD_SSH_USER`, `PROD_SSH_KEY` | `PROD_DEPLOY_ENABLED`, `PROD_DEPLOY_PATH`, `PROD_SYSTEMD_SERVICE`, `PROD_HEALTH_URL`, `PROD_REPOSITORY_URL` |
-
-Semantic-release is also opt-in. Set `RELEASE_ENABLED=true` and provide `RELEASE_TOKEN` when the repository rules allow that token to push release commits and tags to `main`.
+See [CI/CD configuration](docs/en/ci-cd.md) for the exact secrets and variables.
 
 ## Workflows
 
@@ -105,14 +99,14 @@ uv run poe tag             # Preview the next semantic-release version
 uv run poe init -y         # Initialize a new project from the template
 ```
 
-## Documentation
+## What To Keep
 
 | Document | Description |
 | --- | --- |
+| [Agent guide](AGENTS.md) | First-read instructions for AI coding agents |
+| [Quickstart](docs/en/quickstart.md) | Initialize a new project and configure GitHub |
 | [Git workflow](docs/en/git-workflow.md) | Branch, PR, release, and backmerge rules |
-| [GitHub setup](docs/en/github-setup.md) | Branch protection, merge settings, secrets, and variables |
-| [Development workflow](docs/en/development-workflow.md) | Day-to-day feature, release, and hotfix flow |
-| [Features](docs/en/features.md) | Template capabilities and workflow overview |
+| [CI/CD configuration](docs/en/ci-cd.md) | Workflow behavior, secrets, and variables |
 
 ## Requirements
 

diff --git a/README_zh.md b/README_zh.md
@@ -1,16 +1,17 @@
-# UV Python 项目模板
+# Vibecoding Python 起步仓库
 
 [![Built with UV](https://img.shields.io/badge/built%20with-uv-7966C7)](https://github.com/astral-sh/uv)
 [![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-%23FE5196)](https://www.conventionalcommits.org)
 [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
 
 [English](README.md) | [文档](docs/)
 
-> 基于 uv 的生产项目模板，内置 GitHub Actions、语义化发版、Git 治理，以及可选启用的测试/生产部署流程。
+> 面向 vibecoding 的最小 Python 起步仓库：干净的 uv 默认配置、agent 入口文档、严格 Git 工作流、CI 治理，以及可选部署。
 
 ## 开箱能力
 
 - 使用 uv 快速初始化并重命名项目
+- `AGENTS.md` 让 AI coding agent 进仓库后先读规则
 - `dev`/`main` 双长期分支模型
 - PR title 和落地 commit 双重治理
 - Python CI 和可选前端构建
@@ -67,22 +68,15 @@ hotfix/*
 
 ## 部署 Profile
 
-CI 和 Git 治理默认启用。部署能力通过 GitHub Variables 显式开启。
+CI 和 Git 治理默认启用。部署和 release 自动化通过 GitHub Variables 显式开启。
 
 | Profile | Variables | 行为 |
 | --- | --- | --- |
-| `ci-only` | 无 | 只跑 CI、治理和 semantic-release |
+| `ci-only` | 无 | 只跑 CI、PR governance 和 commit governance |
 | `prod-only` | `PROD_DEPLOY_ENABLED=true` | `main` 发版后部署生产 |
 | `test-and-prod` | `TEST_DEPLOY_ENABLED=true`, `PROD_DEPLOY_ENABLED=true` | `dev` 部署测试，`main` 发版后部署生产 |
 
-常用部署配置：
-
-| 环境 | Secrets | Variables |
-| --- | --- | --- |
-| 测试 | `TEST_SSH_HOST`, `TEST_SSH_USER`, `TEST_SSH_KEY` | `TEST_DEPLOY_ENABLED`, `TEST_DEPLOY_PATH`, `TEST_SYSTEMD_SERVICE`, `TEST_HEALTH_URL`, `TEST_REPOSITORY_URL` |
-| 生产 | `PROD_SSH_HOST`, `PROD_SSH_USER`, `PROD_SSH_KEY` | `PROD_DEPLOY_ENABLED`, `PROD_DEPLOY_PATH`, `PROD_SYSTEMD_SERVICE`, `PROD_HEALTH_URL`, `PROD_REPOSITORY_URL` |
-
-semantic-release 也需要显式启用。仓库规则允许某个 token 向 `main` 推 release commit 和 tag 后，设置 `RELEASE_ENABLED=true` 并提供 `RELEASE_TOKEN`。
+具体 secrets 和 variables 见 [CI/CD 配置](docs/zh/ci-cd.zh.md)。
 
 ## Workflows
 
@@ -106,14 +100,14 @@ uv run poe tag             # 预览下一次 semantic-release 版本
 uv run poe init -y         # 初始化新项目
 ```
 
-## 文档
+## 应该保留的文档
 
 | 文档 | 说明 |
 | --- | --- |
+| [Agent guide](AGENTS.md) | AI coding agent 第一入口 |
+| [快速开始](docs/zh/quickstart.zh.md) | 初始化新项目并配置 GitHub |
 | [Git 工作流](docs/zh/git-workflow.zh.md) | 分支、PR、发版和 backmerge 规则 |
-| [GitHub 设置](docs/zh/github-setup.zh.md) | 分支保护、merge 设置、secrets 和 variables |
-| [开发流程](docs/zh/development-workflow.zh.md) | 日常功能、发版和 hotfix 流程 |
-| [功能特性](docs/zh/features.zh.md) | 模板能力和 workflow 概览 |
+| [CI/CD 配置](docs/zh/ci-cd.zh.md) | Workflow 行为、secrets 和 variables |
 
 ## 环境要求
 

diff --git a/docs/README.md b/docs/README.md
@@ -2,16 +2,12 @@
 
 ## English
 
-- [Getting Started](en/getting-started.md)
+- [Quickstart](en/quickstart.md)
 - [Git Workflow](en/git-workflow.md)
-- [GitHub Setup](en/github-setup.md)
-- [Development Workflow](en/development-workflow.md)
-- [Features](en/features.md)
+- [CI/CD Configuration](en/ci-cd.md)
 
 ## 中文
 
-- [快速开始](zh/getting-started.zh.md)
+- [快速开始](zh/quickstart.zh.md)
 - [Git 工作流](zh/git-workflow.zh.md)
-- [GitHub 设置](zh/github-setup.zh.md)
-- [开发流程](zh/development-workflow.zh.md)
-- [功能特性](zh/features.zh.md)
+- [CI/CD 配置](zh/ci-cd.zh.md)
diff --git a/docs/en/ci-cd.md b/docs/en/ci-cd.md
@@ -0,0 +1,69 @@
+# CI/CD Configuration
+
+## Workflows
+
+| Workflow | Trigger | Default behavior |
+| --- | --- | --- |
+| `ci.yml` | PR and push to `dev`/`main` | Python checks, optional frontend build, shell syntax checks |
+| `pr-governance.yml` | PR to `dev`/`main` | Validates Conventional Commit PR titles |
+| `commit-governance.yml` | Push to `dev`/`main` | Validates landed first-parent commit subjects |
+| `deploy-test.yml` | Push to `dev`, manual | Skipped unless `TEST_DEPLOY_ENABLED=true` |
+| `release.yml` | Push to `main`, manual | Skipped unless `RELEASE_ENABLED=true`; production deploy is also opt-in |
+| `backmerge-main-to-dev.yml` | Manual | Recovery workflow for `main -> dev` backmerge |
+
+## Always-On Checks
+
+The template assumes these checks are safe for every project:
+
+- Python quality: `uv sync --frozen --group dev` and `uv run poe check`
+- Optional frontend quality when `src/frontend/package-lock.json` exists
+- Shell syntax for `scripts/cicd/*.sh` and `scripts/deploy/*.sh`
+- PR and commit governance
+
+## Optional Test Deploy
+
+Set `TEST_DEPLOY_ENABLED=true` only when the project has a separate test or staging host.
+
+Secrets:
+
+- `TEST_SSH_HOST`
+- `TEST_SSH_USER`
+- `TEST_SSH_KEY`
+
+Variables:
+
+- `TEST_DEPLOY_PATH`
+- `TEST_SYSTEMD_SERVICE`
+- `TEST_HEALTH_URL`
+- `TEST_REPOSITORY_URL`
+
+## Optional Production Deploy
+
+Set `PROD_DEPLOY_ENABLED=true` only when production SSH deployment is configured.
+
+Secrets:
+
+- `PROD_SSH_HOST`
+- `PROD_SSH_USER`
+- `PROD_SSH_KEY`
+
+Variables:
+
+- `PROD_DEPLOY_PATH`
+- `PROD_SYSTEMD_SERVICE`
+- `PROD_HEALTH_URL`
+- `PROD_REPOSITORY_URL`
+
+## Optional Release Automation
+
+Set `RELEASE_ENABLED=true` only after `RELEASE_TOKEN` can push release commits and tags to `main` under the repository ruleset.
+
+Required secret:
+
+- `RELEASE_TOKEN`
+
+Required variable:
+
+- `RELEASE_ENABLED`
+
+If release automation is disabled, `release.yml` is skipped and `main` still receives CI and commit governance.
diff --git a/docs/en/development-workflow.md b/docs/en/development-workflow.md
diff --git a/docs/en/features.md b/docs/en/features.md