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