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

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.

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.