Initial commit

existing-project.md

@@ -0,0 +1,173 @@
+# Existing Project Agent Workflow
+
+Use this file when an existing repository should become easier for Codex agents to maintain.
+
+## Objective
+
+Add a Codex-friendly repository baseline without flattening the project's existing structure, README voice, or release process.
+
+## Rules
+
+- Preserve existing application code.
+- Preserve existing README knowledge.
+- Do not rename files or folders unless the project already requires it.
+- Do not replace a working CI pipeline wholesale.
+- Add missing structure gradually.
+- Prefer documenting current reality over inventing a new process.
+
+## Steps
+
+### 1. Inspect First
+
+Run:
+
+```bash
+git status --short
+```
+
+Read:
+
+```text
+README*
+package.json / pyproject.toml / Cargo.toml / go.mod / *.csproj
+.github/workflows/*
+.gitea/workflows/*
+docs/*
+```
+
+Identify:
+
+- stack,
+- package manager,
+- build command,
+- test command,
+- lint command,
+- audit command,
+- release artifacts,
+- current CI,
+- existing release notes or changelog,
+- security-sensitive behavior.
+
+If a matching stack profile exists in `profiles/`, read it before changing commands, CI, or ignore rules.
+
+### 2. Add Agent Context
+
+Add `AGENTS.md` first. Keep it short and factual.
+
+Then add `.codex/project.md` with:
+
+- project purpose,
+- authoritative commands,
+- artifact locations,
+- release process,
+- security constraints.
+
+### 3. Add Documentation Files
+
+Add only missing files:
+
+```text
+SECURITY.md
+CHANGELOG.md
+CONTRIBUTING.md
+docs/security-review.md
+docs/release-checklist.md
+docs/agent-handoff.md
+docs/release-notes.md
+```
+
+If equivalent files already exist, update those instead of duplicating them.
+
+### 4. README Generator Decision
+
+Use README blueprint generation only when it helps.
+
+Use it when:
+
+- README is large enough to benefit from structure,
+- project has downloads or release artifacts,
+- repeated README updates are expected.
+
+Avoid it when:
+
+- README is tiny,
+- project has a strong existing documentation system,
+- generator output would erase project-specific style.
+
+If converting:
+
+1. Copy the current README content into `blueprint.md`.
+2. Add `blueprint.json`.
+3. Keep or add `{{ template:section-line }}` between major README sections.
+4. Add a `readme` command.
+5. Generate `README.md`.
+6. Compare the diff carefully.
+
+The default section divider is the rainbow line from `andreasbm/readme`, configured in `blueprint.json` as `section-line`. Agents should keep it enabled when the project uses generated README files.
+
+### 5. CI Retrofit
+
+If CI already exists:
+
+- add missing audit/check steps,
+- keep existing runner labels,
+- keep existing artifact names unless they are broken,
+- avoid changing deployment behavior.
+
+Treat workflow-run artifacts and Package Registry packages as different outputs. If the project expects user-downloadable packages, confirm there is an explicit package publish step in addition to any `actions/upload-artifact` step. When adding or repairing package publishing, copy build outputs to URL-safe filenames before uploading and verify the final package URL after the workflow succeeds.
+
+If CI does not exist:
+
+- add `.gitea/workflows/build.yml` from the template,
+- remove stack-specific steps that do not apply,
+- keep publishing disabled until credentials and artifact names are known.
+
+For releasable projects, add `.gitea/workflows/security-scan.yml` unless the repository already has equivalent scheduled security automation. If an existing scanner is present, document it in `.codex/project.md` instead of duplicating it.
+
+For active repositories, add `.gitea/workflows/repo-cleanup.yml` unless equivalent cleanup checks already exist. Keep cleanup automation non-destructive and document intentional exceptions.
+
+For projects with dependencies, add `.gitea/workflows/dependency-check.yml` unless equivalent dependency update or dependency audit checks already exist. Keep it report-only.
+
+For releasable projects, add `.gitea/workflows/release-dry-run.yml` unless equivalent release readiness checks already exist. It must not tag, publish, or create releases.
+
+For Codex-maintained projects, add `.gitea/workflows/template-compliance.yml` unless equivalent agent-context checks already exist. Preserve documented project-specific exceptions.
+
+### 6. Security Review
+
+Fill `docs/security-review.md` with known facts.
+
+At minimum check for:
+
+```text
+eval
+dynamic Function
+unsafe HTML injection
+shell execution
+external network calls
+file writes
+secret persistence
+committed .env files
+```
+
+Use the stack-native audit command when possible:
+
+| Stack | Audit command |
+| --- | --- |
+| Node | `npm audit --omit=dev --audit-level=high` |
+| Python | `pip-audit` or `uv pip audit` |
+| Rust | `cargo audit` |
+| Go | `govulncheck ./...` |
+| .NET | `dotnet list package --vulnerable` |
+
+### 7. Finish
+
+Before final response:
+
+- run `git diff --check`,
+- run the smallest reliable verification command,
+- 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,
+- list files changed,
+- mention any skipped checks,
+- do not create a release unless explicitly requested.
+