From 5c9f06c16537675b0fa621ff6235a6365eb2def7 Mon Sep 17 00:00:00 2001 From: Erich Blume Date: Tue, 3 Mar 2026 19:25:14 -0800 Subject: [PATCH] Add README and ensure TODO markers at all template customization points Adds a README.md describing the template and how to fork it. Adds TODO comments to Dagger config, Quartz config, and CI workflow where they were missing. Adds a "First-Time Setup" section to CLAUDE.md that instructs Claude to proactively suggest resolving TODOs. Co-Authored-By: Claude Opus 4.6 --- .dagger/pyproject.toml | 1 + .dagger/src/project_template_ci/__init__.py | 1 + .dagger/src/project_template_ci/main.py | 1 + .forgejo/workflows/build.yaml | 1 + CLAUDE.md | 8 +++ README.md | 59 +++++++++++++++++++++ dagger.json | 1 + docs/quartz.config.ts | 4 +- docs/quartz.layout.ts | 2 +- 9 files changed, 75 insertions(+), 3 deletions(-) create mode 100644 README.md diff --git a/.dagger/pyproject.toml b/.dagger/pyproject.toml index 1003178..b42621c 100644 --- a/.dagger/pyproject.toml +++ b/.dagger/pyproject.toml @@ -1,4 +1,5 @@ [project] +# TODO: Rename to match your project (also rename the src/ directory) name = "project-template-ci" version = "0.1.0" requires-python = ">=3.13" diff --git a/.dagger/src/project_template_ci/__init__.py b/.dagger/src/project_template_ci/__init__.py index ff55008..5ff5a10 100644 --- a/.dagger/src/project_template_ci/__init__.py +++ b/.dagger/src/project_template_ci/__init__.py @@ -1,3 +1,4 @@ +# TODO: Update module docstring and class name to match your project """Project Template CI — Dagger build functions.""" from .main import ProjectTemplateCi as ProjectTemplateCi diff --git a/.dagger/src/project_template_ci/main.py b/.dagger/src/project_template_ci/main.py index 9934417..46b8ccb 100644 --- a/.dagger/src/project_template_ci/main.py +++ b/.dagger/src/project_template_ci/main.py @@ -2,6 +2,7 @@ import dagger from dagger import dag, function, object_type +# TODO: Rename class to match your project (e.g. MyProjectCi) @object_type class ProjectTemplateCi: @function diff --git a/.forgejo/workflows/build.yaml b/.forgejo/workflows/build.yaml index f117197..381aa98 100644 --- a/.forgejo/workflows/build.yaml +++ b/.forgejo/workflows/build.yaml @@ -221,6 +221,7 @@ jobs: exit 0 fi + # TODO: Update git identity to match your Forgejo instance git config user.name "Forgejo Actions" git config user.email "actions@forge.example.com" diff --git a/CLAUDE.md b/CLAUDE.md index 490c8fa..54dc58f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -11,6 +11,14 @@ Guidance for Claude Code working in this repository. See also [[ai-assistance-gu **Shell:** The user's shell is **fish**. Use `$status` not `$?` for exit codes. Use fish syntax in interactive examples. +## First-Time Setup + +This repository is a **project template**. All customization points are marked with `TODO` comments throughout the codebase. Before any other work, you should: + +1. **Suggest resolving TODOs first.** Even if the user gives you a different task, check whether TODOs remain by searching for `TODO` across all files. If unresolved TODOs exist, inform the user that the template hasn't been fully customized yet and suggest resolving them first (the user may decline — that's fine, proceed with their request). +2. **To resolve TODOs:** search all files for `TODO`, update each value to match the new project, rename the `.dagger/src/project_template_ci/` directory, and verify nothing was missed. +3. **When all TODOs are resolved:** delete this "First-Time Setup" section entirely from `CLAUDE.md` — it is only needed once. + ## Rules 1. **Always run `mise run ai-docs` at session start** diff --git a/README.md b/README.md new file mode 100644 index 0000000..5b3b2fb --- /dev/null +++ b/README.md @@ -0,0 +1,59 @@ +# project-template + +A personal project template with opinionated infrastructure for documentation, CI, and AI-assisted development. + +## What's Included + +- **Documentation** — [Diataxis](https://diataxis.fr/)-structured docs built with [Quartz](https://quartz.jzhao.xyz/) +- **Changelog** — [Towncrier](https://towncrier.readthedocs.io/) fragment-based changelog +- **CI/CD** — [Dagger](https://dagger.io/) pipelines + [Forgejo](https://forgejo.org/) Actions workflow for releases +- **Pre-commit hooks** — [prek](https://github.com/dustinblackman/prek) with linting, formatting, secret detection +- **AI assistance** — `CLAUDE.md` + structured docs for Claude Code (C0/C1/C2 change process, Mikado method) +- **Task runner** — [mise](https://mise.jdx.dev/) tasks for docs validation, Mikado chain management, and more + +## Forking This Template + +The template contains `TODO` markers at every point that needs customization. To set up a new project: + +1. Fork or copy this repository +2. Search for `TODO` across all files — each one marks a value you need to update: + - Project name and description (`CLAUDE.md`, `docs/index.md`) + - Forgejo/forge instance URLs (`build.yaml`, `mise-tasks/docs-mikado`, `mise-tasks/pr-comments`) + - Dagger module name and class (`dagger.json`, `.dagger/`) + - Quartz site title and URLs (`docs/quartz.config.ts`, `docs/quartz.layout.ts`) + - CI git identity (`.forgejo/workflows/build.yaml`) +3. Rename the `.dagger/src/project_template_ci/` directory to match your new Dagger module name +4. Remove the "First-Time Setup" section from `CLAUDE.md` once all TODOs are resolved +5. Delete this "Forking This Template" section from `README.md` and write your own project description + +If you use Claude Code, it will prompt you to resolve these TODOs at the start of your first session. + +## Getting Started + +```bash +# Install git hooks +prek install && prek install --hook-type commit-msg + +# Run all pre-commit checks +prek run --all-files + +# List available tasks +mise tasks + +# Build docs (requires Dagger) +dagger call build-docs --src=. --version=dev export --path=./docs-dev.tar.gz +``` + +## Project Structure + +``` +./docs/ # documentation (Diataxis, Quartz) +./docs/changelog.d/ # towncrier fragments +./.dagger/ # dagger pipelines +./.forgejo/ # forgejo-runner actions and workflows +./mise-tasks/ # scripts via `mise run` +``` + +## License + + diff --git a/dagger.json b/dagger.json index 673dea1..9003632 100644 --- a/dagger.json +++ b/dagger.json @@ -1,4 +1,5 @@ { + "_comment": "TODO: Rename 'project-template-ci' to match your project", "name": "project-template-ci", "engineVersion": "v0.19.11", "sdk": { diff --git a/docs/quartz.config.ts b/docs/quartz.config.ts index db52879..047d796 100644 --- a/docs/quartz.config.ts +++ b/docs/quartz.config.ts @@ -7,13 +7,13 @@ import * as Plugin from "./quartz/plugins" */ const config: QuartzConfig = { configuration: { - pageTitle: "Project Docs", + pageTitle: "Project Docs", // TODO: Update to your project name pageTitleSuffix: "", enableSPA: true, enablePopovers: true, analytics: null, locale: "en-US", - baseUrl: "CHANGEME.example.com", + baseUrl: "CHANGEME.example.com", // TODO: Update to your docs site URL ignorePatterns: ["private", "templates", ".obsidian"], defaultDateType: "modified", theme: { diff --git a/docs/quartz.layout.ts b/docs/quartz.layout.ts index 888f89e..1573cb8 100644 --- a/docs/quartz.layout.ts +++ b/docs/quartz.layout.ts @@ -13,7 +13,7 @@ export const sharedPageComponents: SharedLayout = { afterBody: [], footer: Component.Footer({ links: { - "Repository": "https://CHANGEME.example.com/owner/repo", + "Repository": "https://CHANGEME.example.com/owner/repo", // TODO: Update to your repo URL }, }), }