first commit

existing-project.md

@@ -0,0 +1,151 @@
+# 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.
+
+### 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
+docs/security-review.md
+docs/release-checklist.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. Add a `readme` command.
+4. Generate `README.md`.
+5. Compare the diff carefully.
+
+### 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.
+
+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.
+
+### 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,
+- list files changed,
+- mention any skipped checks,
+- do not create a release unless explicitly requested.
+