codex-agent-repository-kit/new-repository.md

# 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.

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.