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:

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:

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:

PROJECT_NAME
PROJECT_DESCRIPTION
REPOSITORY_OWNER
REPOSITORY_NAME

Derive REPOSITORY_OWNER and REPOSITORY_NAME from the target repository remote URL or GITHUB_REPOSITORY. Do not copy the owner from this repository kit's own remote.

Optional:

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:

dev
lint
test
build
audit
readme
release:check

For Node projects, a reasonable baseline is:

{
  "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:

Overview
Features
Installation
Development
Downloads or Artifacts
Security
Release
Project Info

6. Add CI

Create the smallest useful workflow:

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.