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
2 changes: 1 addition & 1 deletion .github/workflows/ci.yml.example
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,6 @@ jobs:
name: test
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
- uses: actions/checkout@v7
# Replace with project-specific setup and validation commands.
- run: echo "Configure CI for this project"
6 changes: 3 additions & 3 deletions .github/workflows/review.yml
Original file line number Diff line number Diff line change
Expand Up @@ -11,15 +11,15 @@ jobs:
name: repository checks
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
- uses: actions/checkout@v7
- run: ./scripts/check-repository.sh

pr-title:
name: conventional PR title
if: github.event_name == 'pull_request'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
- uses: actions/checkout@v7
- run: ./scripts/check-pr-title.sh "$PR_TITLE"
env:
PR_TITLE: ${{ github.event.pull_request.title }}
Expand All @@ -30,7 +30,7 @@ jobs:
if: github.event_name == 'pull_request' && github.event.pull_request.user.type != 'Bot'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
- uses: actions/checkout@v7
- run: printf '%s\n' "$PR_BODY" | ./scripts/check-pr-body.sh
env:
PR_BODY: ${{ github.event.pull_request.body }}
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,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 decisions and detailed execution plans. Current-state documentation owns implemented behavior.
- Use `docs/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 Down
3 changes: 2 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,8 @@

## Unreleased

- Workflows pin `actions/checkout` to the v7.0.1 commit SHA; downstream repositories take action bumps from this template instead of editing `review.yml` locally.
- Workflows use `actions/checkout@v7`; actions are referenced by their latest major version tag, not a commit SHA. Downstream repositories take action upgrades from this template instead of editing `review.yml` locally.
- Specs moved from `specs/` to `docs/specs/`, next to `docs/plans/`.
- `configure-github-repository.sh` accepts `--approvals N` (use 0 for a single maintainer) and repeatable `--check NAME` for project CI jobs.
- Removed trailing blank lines that failed `git diff --cached --check` in repositories copying the template files.
- Plans now pair technical decisions with a detailed execution plan: preconditions, completion contract, ordered tasks with exit conditions, validation ledger, and rollback per batch.
Expand Down
6 changes: 4 additions & 2 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -92,7 +92,7 @@ Every change needs a requirement record. Use the smallest set of artifacts that
| Technical refactor without changed user behavior | Detailed Plan with compatibility and acceptance conditions |
| Narrow maintenance, tests, or documentation | Requirement and PR checklist; a separate Plan only when useful |

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.
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 [`docs/specs/`](docs/specs/). A small change may keep both sections in the PR description. Split only when each slice has an independently demonstrable outcome.

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.

Expand Down Expand Up @@ -125,7 +125,7 @@ Keep each documentation surface focused:
- Use `README.md` for orientation, quick start, and current user-facing behavior.
- 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/specs/` for active product behavior and acceptance contracts.
- 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.

Expand Down Expand Up @@ -164,6 +164,8 @@ Keep package or deploy contents intentional. If a file should ship, verify it ap

Run `./scripts/check-repository.sh` locally before opening review. This generic check does not replace stack-specific tests, but it catches missing template files, tracked local artifacts, obvious secrets, private paths, and drift in review templates.

Workflows reference actions by their latest major version tag, such as `actions/checkout@v7`, not by commit SHA. Workflow files copied from this template take action upgrades from the template rather than local edits.

## Local Git Hooks

Install local hooks after cloning or creating a repository from this template:
Expand Down
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ Use this template when creating a new project that should have consistent contri
- `.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/specs/0000-template.md` for active product behavior.
- `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.
Expand All @@ -53,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 decisions and execution plans in `docs/plans/`, and current product or engineering knowledge in `docs/`.
Keep collaboration policy in `AGENTS.md` and `CONTRIBUTING.md`, active behavior in `docs/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 @@ -16,7 +16,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.
- [`specs/`](specs/) declares active product behavior and acceptance contracts.
- [`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
2 changes: 1 addition & 1 deletion specs/0000-template.md → docs/specs/0000-template.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Spec 0000: Product Behavior

Use this template for an active declarative contract. Follow the [SDD Workflow And Document Lifecycle](../CONTRIBUTING.md#sdd-workflow-and-document-lifecycle) for the complete workflow.
Use this template for an active declarative contract. Follow the [SDD Workflow And Document Lifecycle](../../CONTRIBUTING.md#sdd-workflow-and-document-lifecycle) for the complete workflow.

## Status

Expand Down
2 changes: 1 addition & 1 deletion specs/README.md → docs/specs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,4 +4,4 @@ Active Specs define interactions, scope, failure behavior, compatibility, and ac

Start from [`0000-template.md`](0000-template.md). Use `Draft`, `Accepted`, or `Superseded`. Give acceptance scenarios stable IDs and use Given/When/Then where useful. Link them to tests. No separate BDD document or framework is required. Technical decisions and the detailed execution plan belong in the paired Plan.

Follow the [SDD lifecycle](../CONTRIBUTING.md#sdd-workflow-and-document-lifecycle): migrate lasting behavior to tests and current-state docs before deleting completed Specs and Plans in the final delivery PR. Keep unfinished work active.
Follow the [SDD lifecycle](../../CONTRIBUTING.md#sdd-workflow-and-document-lifecycle): migrate lasting behavior to tests and current-state docs before deleting completed Specs and Plans in the final delivery PR. Keep unfinished work active.
2 changes: 1 addition & 1 deletion scripts/check-repository.sh
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,7 @@ required_files=(
"scripts/install-git-hooks.sh"
"scripts/configure-github-repository.sh"
"scripts/lib/review-sections.sh"
"specs/0000-template.md"
"docs/specs/0000-template.md"
"docs/plans/0000-template.md"
)

Expand Down
Loading