Initial commit

2026-05-04 09:03:49 +00:00
commit 592db184a2
29 changed files with 2739 additions and 0 deletions
--- a/new-repository.md
+++ b/new-repository.md
@@ -0,0 +1,185 @@
+# New Repository Agent Workflow
+
+Use this file as the agent-facing workflow for a fresh repository.
+
+## Objective
+
+Create a small, clear repository baseline that helps future Codex agents understand:
+
+- what the project is,
+- how to build and verify it,
+- how releases are prepared,
+- what security rules matter,
+- where generated artifacts are expected.
+
+## Steps
+
+### 1. Inspect The Repo
+
+Run:
+
+```bash
+git status --short
+```
+
+Identify:
+
+- repository name,
+- likely stack,
+- package manager or build tool,
+- expected artifact type,
+- whether the repo is app, service, library, script, documentation, or infrastructure.
+
+If a matching stack profile exists in `profiles/`, read it before choosing commands.
+
+### 2. Copy Baseline Files
+
+Create directories as needed and copy:
+
+```text
+files/AGENTS.md              -> AGENTS.md
+files/project.md             -> .codex/project.md
+files/SECURITY.md            -> SECURITY.md
+files/CHANGELOG.md           -> CHANGELOG.md
+files/CONTRIBUTING.md        -> CONTRIBUTING.md
+files/gitignore.template     -> .gitignore
+files/release-checklist.md   -> docs/release-checklist.md
+files/security-review.md     -> docs/security-review.md
+files/agent-handoff.md       -> docs/agent-handoff.md
+files/release-notes.md       -> docs/release-notes.md
+files/blueprint.md           -> blueprint.md
+files/blueprint.json         -> blueprint.json
+files/build-gitea.yml        -> .gitea/workflows/build.yml
+files/security-scan-gitea.yml -> .gitea/workflows/security-scan.yml
+files/repo-cleanup-gitea.yml -> .gitea/workflows/repo-cleanup.yml
+files/dependency-check-gitea.yml -> .gitea/workflows/dependency-check.yml
+files/release-dry-run-gitea.yml -> .gitea/workflows/release-dry-run.yml
+files/template-compliance-gitea.yml -> .gitea/workflows/template-compliance.yml
+```
+
+Skip `build-gitea.yml` when the project has no CI target yet. Skip README blueprint files when the project should keep a very small manual README.
+
+### 3. Replace Placeholders
+
+Replace only with facts that are known.
+
+Required:
+
+```text
+PROJECT_NAME
+PROJECT_DESCRIPTION
+REPOSITORY_OWNER
+REPOSITORY_NAME
+```
+
+Optional:
+
+```text
+PACKAGE_NAME
+ARTIFACT_NAME
+ARTIFACT_OUTPUT_DIRECTORY
+AUTHOR_NAME
+PROJECT_STACK
+DOWNLOAD_URL
+BUILD_COMMAND
+TEST_COMMAND
+LINT_COMMAND
+AUDIT_COMMAND
+```
+
+Delete sections that do not apply.
+
+### 4. Add Standard Commands
+
+Prefer these command names when the stack supports them:
+
+```text
+dev
+lint
+test
+build
+audit
+readme
+release:check
+```
+
+For Node projects, a reasonable baseline is:
+
+```json
+{
+  "scripts": {
+    "lint": "tsc --noEmit",
+    "build": "tsc --noEmit",
+    "audit": "npm audit --omit=dev --audit-level=high",
+    "readme": "npx --yes @appnest/readme generate -i blueprint.md -c blueprint.json",
+    "release:check": "npm run lint && npm run build"
+  }
+}
+```
+
+Do not add commands that cannot run.
+
+### 5. Create Or Update README
+
+If using the generator:
+
+1. Fill `blueprint.md`.
+2. Fill `blueprint.json`.
+3. Keep `{{ template:section-line }}` between major README sections.
+4. Add a `readme` command.
+5. Generate `README.md`.
+6. Commit `README.md`, `blueprint.md`, and `blueprint.json`.
+
+The default section divider is the rainbow line from `andreasbm/readme`, configured in `blueprint.json` as `section-line`. Agents should keep it enabled for generated README files.
+
+If not using the generator, keep a manual README with the same main sections:
+
+```text
+Overview
+Features
+Installation
+Development
+Downloads or Artifacts
+Security
+Release
+Project Info
+```
+
+### 6. Add CI
+
+Create the smallest useful workflow:
+
+```text
+checkout
+setup runtime
+install dependencies
+audit
+lint/test
+build
+upload artifacts
+```
+
+Only publish artifacts to a package registry when the artifact names and credentials are known. `actions/upload-artifact` creates a workflow-run artifact, not a Gitea Package Registry package. If users need a package/download entry, add a separate generic package upload step with `REGISTRY_TOKEN`, copy artifacts to URL-safe filenames before upload, and verify the final package URL after the workflow succeeds.
+
+For releasable projects, config tools, apps, or repositories that process user data, secrets, or deployment files, also add `.gitea/workflows/security-scan.yml`. Keep the scheduled workflow conservative and review false positives before silencing checks.
+
+For active repositories, also add `.gitea/workflows/repo-cleanup.yml`. It should report cleanup candidates only; it must not delete files, branches, packages, or releases automatically.
+
+For projects with dependencies, add `.gitea/workflows/dependency-check.yml`. It should report dependency health only; it must not edit dependency manifests or lockfiles automatically.
+
+For releasable projects, add `.gitea/workflows/release-dry-run.yml`. It should verify release readiness only; it must not create tags, releases, packages, or artifacts automatically.
+
+For Codex-maintained projects, add `.gitea/workflows/template-compliance.yml`. It should verify agent context and template hygiene without overwriting project-specific conventions.
+
+### 7. Finish
+
+Before final response:
+
+- run formatting or validation if available,
+- run the cheapest reliable verification command,
+- check `git diff --check`,
+- if using Gitea Actions, poll the pushed workflow run until it reaches a terminal state; for private `git.wilkensxl.de` repositories, use a locally set `GITEA_TOKEN` for read-only API status checks when available,
+- if the pushed workflow fails or is cancelled, inspect the failing job/logs, fix in scope, push again, and repeat the workflow check loop; fixing and pushing is not a stopping point,
+- summarize changed files,
+- do not create a release unless explicitly requested.
+