project-bootstrapper

name

project-bootstrapper

description

Bootstrap a repository derived from this template into a concrete project. Use when Codex needs to clarify the project purpose with the user, choose or confirm the service name, replace `TemplateService` placeholders, refactor project and agentic files to the new brand/scope, reset inherited `.codex/notes` memory, trim `/docs` to project-relevant material, guide `.env` and dependency setup, and remove bootstrap-only traces once initialization is complete. Ignore this skill entirely when a repository-root `.ignore-bootstrap` file exists.

Project Bootstrapper

Bootstrap a fresh clone once, then remove the bootstrap scaffolding when the repository becomes a normal project. Keep the process collaborative with the user, but do not block on unnecessary questions when repository evidence already answers them.

Guardrails

• Check for a repository-root .ignore-bootstrap file before doing anything else. If it exists, stop and ignore this skill and every bootstrap-only instruction.
• Treat bootstrap as a one-time initialization flow for repositories derived from the template. Do not re-run full bootstrap on a repository that has already been branded unless the user explicitly asks for a re-bootstrap.
• Preserve the template architectural defaults unless the user explicitly changes them: single ASP.NET Core host, REST under /api/*, MCP under /mcp, runtime defaults driven by environment variables.
• Keep changes self-consistent across code, docs, Docker artifacts, environment files, validation scripts, and agentic files.

Workflow

1. Confirm bootstrap mode

• Verify that the repository still looks like a template by searching for placeholders such as TemplateService, template README copy, placeholder observability names, or template Docker/image names.
• If placeholders are already gone, limit work to the user's requested cleanup or refinement instead of forcing a second bootstrap.
• Record whether the repository should remain a reusable template. The default assumption is no for consumer projects and yes only when the user is actively evolving the template itself.

2. Define project identity with the user

• Clarify the target outcome in the smallest useful scope:
  • what the service does
  • who or what consumes it
  • the preferred project/service name
  • any external systems, containers, or protocols that must be present on day one
• If the user does not provide a name, default to the current repository root directory name and normalize it for solution, project, namespace, image, and service-name usage.
• Produce a short bootstrap contract before refactoring:
  • chosen project name
  • one-sentence objective
  • key integrations or dependencies
  • assumptions that still need confirmation

3. Refactor the template into the project

• Replace TemplateService and other template placeholders across:
  • solution and project names
  • namespaces and assembly names
  • Docker image names and compose service labels
  • README and public-facing copy
  • Observability:ServiceName, .env.example, and startup defaults
• Search the repository for template markers instead of editing only the obvious files.
• Update agentic files when they still describe the template instead of the target project. This includes AGENTS.md, notes, decisions, and any skill metadata that should survive after bootstrap.
• Remove any inherited .codex/notes/ content from the template so the new project starts with no prior operational memory. If the project will still use the note system, recreate the structure cleanly after bootstrap instead of keeping old notes.
• Keep REST controllers under Controllers/, MCP behavior under Mcp/, and both delegating to Services/.

4. Guide environment and dependency setup

• Review .env.example, docker-compose.yml, Dockerfile, scripts, and docs to identify the expected runtime dependencies.
• Review docs/ and remove documents that are not useful to the new project. Keep only material that still provides value after the template brand and scope are gone.
• If Docker is available, inspect local containers, compose services, images, and networks to discover useful integrations already present, such as Seq, databases, brokers, or supporting services.
• Help the user create .env from .env.example with values justified by the discovered integrations and the chosen project scope.
• Distinguish clearly between:
  • values required for first run
  • optional observability integrations
  • integrations that can stay unset until later

5. Validate the initialized repository

• Run the relevant checks after the rename/refactor. Prefer the strongest low-cost signals first.
• For a repository that still behaves like this template, use:
  • dotnet build <solution> -c Release
  • dotnet test <solution> -c Release
  • pwsh -File scripts/validate-template.ps1
• For a consumer project, replace template-only validation with the project's actual build, test, and smoke checks once names and scripts have been updated.
• Report unresolved placeholders, skipped checks, and manual follow-ups explicitly.

6. Remove bootstrap-only traces

• Perform this step only after project identity, refactor, environment guidance, and validation are complete.
• Remove bootstrap-only material that no longer serves the initialized project, unless the repository is intentionally still a reusable template.
• Clean up bootstrap guidance from agentic surfaces, including:
  • the Template Bootstrap section or equivalent bootstrap instructions in AGENTS.md
  • the project-bootstrapper skill and any bootstrap-only notes
  • bootstrap-specific decision or issue entries that only existed to operate the template initialization
• Confirm that inherited .codex/notes/ content is gone and that /docs contains only project-relevant documents before removing the bootstrap scaffolding itself.
• Keep durable project knowledge. Delete only the scaffolding that was useful exclusively during initialization.

Completion Criteria

• The repository name, namespaces, docs, container metadata, and observability settings match the chosen project identity.
• Template-inherited .codex/notes/ content has been removed, or the note system has been intentionally reinitialized from zero.
• /docs contains only documentation that is still useful to the initialized project.
• .env setup guidance exists and reflects the real dependencies found in repository config or local containers.
• Template placeholders have been removed or explicitly justified.
• Bootstrap-only instructions are gone unless the repository still needs to act as a template.