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
3 changes: 2 additions & 1 deletion .github/pull_request_template.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
Title format: `type(scope): summary`
Title format: `type(scope): summary`, in English.

Allowed types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert`.

Expand All @@ -18,6 +18,7 @@ Allowed types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `buil

- [ ] Repository checks: `./scripts/check-repository.sh`
- [ ] PR title: `./scripts/check-pr-title.sh "<title>"`
- [ ] PR description: `./scripts/check-pr-body.sh <body-file>`
- [ ] Format:
- [ ] Lint:
- [ ] Test:
Expand Down
11 changes: 11 additions & 0 deletions .github/workflows/review.yml
Original file line number Diff line number Diff line change
Expand Up @@ -23,3 +23,14 @@ jobs:
- run: ./scripts/check-pr-title.sh "$PR_TITLE"
env:
PR_TITLE: ${{ github.event.pull_request.title }}

pr-body:
name: PR description
# Bot PRs (dependency updates, release PRs) do not use the template; their titles are still checked.
if: github.event_name == 'pull_request' && github.event.pull_request.user.type != 'Bot'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: printf '%s\n' "$PR_BODY" | ./scripts/check-pr-body.sh
env:
PR_BODY: ${{ github.event.pull_request.body }}
3 changes: 2 additions & 1 deletion .gitlab/merge_request_templates/default.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
Title format: `type(scope): summary`
Title format: `type(scope): summary`, in English.

Allowed types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert`.

Expand All @@ -18,6 +18,7 @@ Allowed types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `buil

- [ ] Repository checks: `./scripts/check-repository.sh`
- [ ] MR title: `./scripts/check-pr-title.sh "<title>"`
- [ ] MR description: `./scripts/check-pr-body.sh <body-file>`
- [ ] Format:
- [ ] Lint:
- [ ] Test:
Expand Down
12 changes: 8 additions & 4 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,9 @@ Keep the generic review commands active, and replace the remaining placeholders
# PR/MR title check:
./scripts/check-pr-title.sh "docs: update project template"

# PR/MR description check (file or stdin):
./scripts/check-pr-body.sh pr-body.md

# GitHub repository setup dry run:
./scripts/configure-github-repository.sh --repo OWNER/REPO

Expand All @@ -48,7 +51,7 @@ Do not claim implementation work is complete until the relevant commands pass, o
For non-trivial changes:

1. Understand the requested behavior, affected domain concepts, ownership boundaries, and data flow.
2. Follow the Spec/Plan selection rules in `CONTRIBUTING.md`. Review required design artifacts before implementation. Record technical decisions in the Plan and migrate lasting constraints to current-state documentation.
2. Follow the Spec/Plan selection rules in `CONTRIBUTING.md`. Review required design artifacts before implementation. The Spec states required behavior; the Plan records technical decisions and the ordered tasks, tests, and exit conditions to execute. Do not start a Plan that is blocked on an unresolved decision. Migrate lasting constraints to current-state documentation.
3. Keep the implementation scoped to the task and nearby code.
4. Update tests and documentation when behavior, public contracts, or workflow expectations change.
5. Ensure local Git hooks are installed for the checkout when practical.
Expand All @@ -60,6 +63,7 @@ For non-trivial changes:

- Organize code by domain boundaries, layer boundaries, and test boundaries before mechanical one-file-per-export preferences.
- Keep domain rules, application services, infrastructure adapters, UI/CLI entrypoints, persistence, and test fixtures separated when those responsibilities exist.
- JavaScript or TypeScript projects take shared lint, format, and `tsconfig` rules from the `PerfectPan/lint-config` repository; see its README. Extend those shared configs instead of copying them.
- Do not introduce a shared abstraction unless it removes real duplication, clarifies a boundary, or matches an existing project pattern.
- When a file starts mixing multiple responsibilities or layers, split by responsibility rather than by arbitrary size.
- Substantial product behavior uses one Spec plus one detailed Plan. Technical refactors use a Plan. Record technical choices there before implementation.
Expand All @@ -68,7 +72,7 @@ For non-trivial changes:

- Keep `README.md` focused on orientation, quick start, and current user-facing behavior.
- Use `CONTRIBUTING.md` for contribution workflow.
- Use `specs/` for active product behavior and `docs/plans/` for active technical designs. Current-state documentation owns implemented behavior.
- Use `specs/` for active product behavior and `docs/plans/` for active technical decisions and detailed execution plans. Current-state documentation owns implemented behavior.
- Use `docs/` for durable current-state knowledge such as architecture, development guides, operational runbooks, references, and onboarding tutorials.
- Update `CHANGELOG.md` for user-facing changes unless the change is docs-only or repository-only.
- When behavior, configuration, commands, APIs, deployment, architecture, or operations change, update the relevant docs in the same PR/MR or explain why no docs changed.
Expand All @@ -87,8 +91,8 @@ When an AI agent completes implementation work:

## Review Evidence

- PR/MR titles must follow `type(scope): summary`; use `scripts/check-pr-title.sh` to verify them.
- PR/MR descriptions must include motivation, implementation notes, exact validation commands, skipped gates with reasons, and follow-up risks.
- PR/MR titles must be English and follow `type(scope): summary`, including bot-generated release and dependency PRs such as `chore(release): version packages`; use `scripts/check-pr-title.sh` to verify them.
- PR/MR descriptions must keep every template section and include motivation, implementation notes, exact validation commands, skipped gates with reasons, and follow-up risks. Do not add agent attribution lines such as "Generated with <tool>". Verify the body with `scripts/check-pr-body.sh` before opening or updating the PR/MR. Bot-opened PRs are exempt from the description check, not the title check.
- If a claim depends on logs, screenshots, package output, deployed behavior, or generated artifacts, attach or link the evidence in the PR/MR.
- Update the PR/MR description after substantial code changes, review-driven revisions, rebases that change behavior, or validation reruns.
- Keep GitHub PR and GitLab MR templates in sync if the project uses both hosting styles.
Expand Down
5 changes: 5 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,11 @@

## Unreleased

- Plans now pair technical decisions with a detailed execution plan: preconditions, completion contract, ordered tasks with exit conditions, validation ledger, and rollback per batch.
- Added `scripts/check-pr-body.sh` and a `PR description` review job that require template sections, real Summary and Validation content, and no agent attribution lines.
- PR title checks now reject CJK characters; bot-generated PRs must use conventional titles too.
- Repository checks share one review-section list, match private paths only at a path boundary, and avoid `grep -q` SIGPIPE failures under `pipefail`.
- Documented `PerfectPan/lint-config` as the shared lint, format, and `tsconfig` source for JavaScript and TypeScript projects.
- Replaced the RFC directory with a behavioral Spec plus a detailed technical Plan. Lasting constraints move to current-state docs; Git history keeps retired artifacts.
- Initial project template.
- Added a generic review workflow for repository checks and conventional PR titles.
Expand Down
26 changes: 20 additions & 6 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,9 @@ Replace this section with project-specific setup instructions.
# check a PR or MR title
./scripts/check-pr-title.sh "docs: update project template"

# check a PR or MR description from a file or stdin
./scripts/check-pr-body.sh pr-body.md

# preview GitHub repository protection setup
./scripts/configure-github-repository.sh --repo OWNER/REPO

Expand Down Expand Up @@ -53,6 +56,9 @@ Replace these placeholders after choosing the project stack:
# PR/MR title:
./scripts/check-pr-title.sh "docs: update project template"

# PR/MR description:
./scripts/check-pr-body.sh pr-body.md

# GitHub repository setup dry run:
./scripts/configure-github-repository.sh --repo OWNER/REPO

Expand All @@ -70,8 +76,8 @@ Replace these placeholders after choosing the project stack:
## SDD Workflow And Document Lifecycle

1. Record the problem, affected users or maintainers, in-scope behavior, non-goals, and acceptance conditions.
2. Choose artifacts with the [Change Design Gate](#change-design-gate). Product work defaults to one behavioral Spec and one detailed Plan for the same deliverable. The Spec states interactions and acceptance scenarios. The Plan owns technical design, component and interface changes, data flow, implementation order, and verification.
3. Review the behavior and technical design before implementing the affected scope. The Plan must resolve implementation decisions rather than leave them to the implementer. New behavior revises the Spec. New implementation decisions revise the Plan.
2. Choose artifacts with the [Change Design Gate](#change-design-gate). Product work defaults to one behavioral Spec and one detailed Plan for the same deliverable. The Spec states required behavior: interactions and acceptance scenarios. The Plan owns the technical decisions (design, component and interface changes, data flow) and the detailed execution plan (ordered tasks, tests, exit conditions, validation, and rollback).
3. Review the behavior and technical design before implementing the affected scope. The Plan must resolve implementation decisions rather than leave them to the implementer; keep it blocked while a material decision is unresolved. New behavior revises the Spec. New implementation decisions revise the Plan.
4. Implement inside that boundary. Add evidence for each acceptance condition, or say why existing evidence is enough. Update current-state docs in the same change.
5. Before retiring a completed Spec or Plan, move still-valid behavior, invariants, and operational limits into current-state docs and tests. The final delivery PR may delete the completed files. Keep an unfinished Spec or Plan active.
6. Git history and the delivery PR keep the retired decision. Do not copy completed Specs or Plans into a second archive.
Expand All @@ -88,11 +94,13 @@ Every change needs a requirement record. Use the smallest set of artifacts that

A Spec defines observable interactions, scope, failure behavior, and acceptance examples. Use stable scenario IDs and Given/When/Then where useful. Link scenarios to tests. A Spec does not prescribe components, interfaces, or execution order. Keep active Specs under [`specs/`](specs/). A small change may keep both sections in the PR description. Split only when each slice has an independently demonstrable outcome.

Shared architecture, compatibility, security, and recovery decisions belong in a reviewed Plan. After implementation, move lasting constraints into current-state architecture or operations docs. This template does not keep an RFC directory. Removing a proposal does not mark unimplemented ideas as delivered.
A Plan records technical decisions and the detailed execution plan that implements them. Shared architecture, compatibility, security, and recovery decisions belong in a reviewed Plan. After implementation, move lasting constraints into current-state architecture or operations docs. This template does not keep an RFC directory. Removing a proposal does not mark unimplemented ideas as delivered.

## Implementation Plans

[`docs/plans/`](docs/plans/) contains active technical design documents. Copy [`0000-template.md`](docs/plans/0000-template.md) and keep only the sections that apply. A product plan links its paired Spec. Explain the current constraints, the decisions, the boundaries, the failure and rollback behavior, and how the change will be verified. A file list alone is not a design.
[`docs/plans/`](docs/plans/) contains active Plans: technical decisions plus a detailed execution plan. Copy [`0000-template.md`](docs/plans/0000-template.md) and keep only the sections that apply. A product plan links its paired Spec. Explain the current constraints, the decisions, the boundaries, the failure and rollback behavior, and how the change will be verified. A file list alone is not a design.

The execution plan tells the implementer exactly what to do: preconditions, a completion contract, ordered tasks with files, changes, tests, and exit conditions, a validation ledger, and rollback per batch. Keep the plan blocked while a decision that changes scope, interfaces, data, or rollout is unresolved.

Keep unknown owners, dates, and interfaces marked "unconfirmed". A plan may make feature-specific technical decisions, but it cannot silently override current architecture. At completion, migrate lasting constraints into current-state docs and tests, then delete the completed Spec and plan in the final delivery PR. Keep unfinished scope visible.

Expand All @@ -106,6 +114,8 @@ Maintain the repository around real responsibilities:
- UI, CLI, or API entrypoints translate user or protocol input into application calls.
- Test fixtures and helpers belong near the tests or in clearly named test-support areas.

For JavaScript or TypeScript projects, take shared lint, format, and `tsconfig` rules from the `PerfectPan/lint-config` repository instead of copying them; see its README. Other stacks choose their own tooling.

Avoid splitting code only to satisfy a mechanical one-export rule. Split when a file mixes responsibilities, a component or service needs independent testing, a boundary becomes reusable, or a change would otherwise make review harder. When adding a top-level directory or durable module boundary, document the reason in the PR/MR and record the technical choice in a Plan when the structure affects long-term integration.

## Documentation Standards
Expand All @@ -116,7 +126,7 @@ Keep each documentation surface focused:
- Use `CONTRIBUTING.md` for contribution workflow, review expectations, and repository policy.
- Use `AGENTS.md` for AI-agent instructions.
- Use `specs/` for active product behavior and acceptance contracts.
- Use `docs/plans/` for active technical designs and implementation plans. Migrate lasting decisions into current-state docs.
- Use `docs/plans/` for active technical decisions and detailed execution plans. Migrate lasting decisions into current-state docs.
- Use `docs/` for durable current-state knowledge: architecture, development guides, operational runbooks, references, and onboarding tutorials.

Follow `docs/README.md` when adding or reorganizing project documentation. Update docs in the same change as behavior, configuration, command, API, deployment, architecture, or operational changes. Keep examples runnable when possible; otherwise, label them as illustrative and explain the validation gap.
Expand All @@ -140,6 +150,10 @@ type(scope): summary

Allowed types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert`.

Titles are English; `scripts/check-pr-title.sh` rejects CJK characters. Bot-generated PRs follow the same rule, so configure release and dependency bots to emit titles such as `chore(release): version packages` or `chore(deps): bump <package> to <version>`.

The description keeps every `##` section from the PR/MR template. Summary and Validation must contain real content, not template placeholders. Do not include agent attribution lines such as "Generated with <tool>"; the author is accountable for the content. `scripts/check-pr-body.sh` enforces these rules, and the `PR description` job runs it on every pull request event, including description edits. PRs opened by bot accounts skip the description check, because dependency and release bots write their own bodies; they still must pass the title check. A skipped job still satisfies the required status check.

Update the description when review feedback, rebases, or follow-up commits change the scope or validation result. Reviewers should be able to understand the final state from the PR/MR without reconstructing it from comments.

## Repository Checks
Expand Down Expand Up @@ -170,7 +184,7 @@ Template files do not carry GitHub branch protection settings into every new rep
./scripts/configure-github-repository.sh --repo OWNER/REPO --apply
```

The setup script requires a GitHub account or token with permission to edit repository settings. It protects the default branch by requiring pull requests, one approving review, fresh reviews after new pushes, linear history, resolved conversations, and the `Review` workflow checks named `repository checks` and `conventional PR title`.
The setup script requires a GitHub account or token with permission to edit repository settings. It protects the default branch by requiring pull requests, one approving review, fresh reviews after new pushes, linear history, resolved conversations, and the `Review` workflow checks named `repository checks`, `conventional PR title`, and `PR description`.

## Security Reports

Expand Down
8 changes: 5 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,13 +36,15 @@ Use this template when creating a new project that should have consistent contri
- `docs/README.md` for architecture, development, operations, and reference documentation standards.
- `.github/pull_request_template.md` for PR summaries and validation.
- `.github/ISSUE_TEMPLATE/` for bug and feature reports.
- `.github/workflows/review.yml` for generic repository and PR title checks.
- `.github/workflows/review.yml` for generic repository, PR title, and PR description checks.
- `.githooks/pre-commit` for local commit-time repository checks.
- `.gitlab/merge_request_templates/default.md` for GitLab-style MR summaries.
- `specs/0000-template.md` for active product behavior.
- `docs/plans/0000-template.md` for active technical designs and implementation plans.
- `docs/plans/0000-template.md` for active technical decisions and detailed execution plans.
- `scripts/check-repository.sh` for local and CI repository checks.
- `scripts/check-pr-title.sh` for conventional PR or MR title checks.
- `scripts/check-pr-body.sh` for PR or MR description checks.
- `scripts/lib/review-sections.sh` for the review template sections shared by the checks.
- `scripts/install-git-hooks.sh` for installing local Git hooks.
- `scripts/configure-github-repository.sh` for post-create GitHub branch protection setup.
- `.editorconfig` for consistent text formatting.
Expand All @@ -51,4 +53,4 @@ Use this template when creating a new project that should have consistent contri

Keep this repository generic. Do not add language-specific package files, framework defaults, generated output, or project-specific business logic.

Keep collaboration policy in `AGENTS.md` and `CONTRIBUTING.md`, active behavior in `specs/`, active technical design in `docs/plans/`, and current product or engineering knowledge in `docs/`.
Keep collaboration policy in `AGENTS.md` and `CONTRIBUTING.md`, active behavior in `specs/`, active technical decisions and execution plans in `docs/plans/`, and current product or engineering knowledge in `docs/`.
2 changes: 1 addition & 1 deletion docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ Do not create empty directories just to match this list. Add a section when the
## Spec And Plan Boundary

- [`../specs/`](../specs/) declares active product behavior and acceptance contracts.
- [`plans/`](plans/) contains active technical designs and implementation plans.
- [`plans/`](plans/) contains active technical decisions and detailed execution plans.

The Change Design Gate in [`CONTRIBUTING.md`](../CONTRIBUTING.md) decides which artifacts a change needs. After delivery, lasting constraints belong in current-state `docs/`. Git history keeps the retired Spec or Plan.

Expand Down
Loading
Loading