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

At task start, check for upstream repository updates and apply them immediately with a safe fast-forward pull when the working tree is clean:

git pull --ff-only

If local changes exist, do not overwrite them. Fetch or report the blocker before editing.

Conserve context tokens while inspecting: start with targeted searches and file lists, then read only files that affect the baseline decision. Do not load generated folders, dependency folders, build outputs, or full logs unless they are directly relevant.

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
CI_URL
RELEASES_URL
GITEA_SERVER_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.

Keep Codex kit files tracked in the source repository when they help agents, but exclude them from user-facing release, package, installer, archive, and GitHub/Gitea upload artifacts unless the user explicitly wants repository-maintenance files shipped. Typical excluded paths are AGENTS.md, .codex/, blueprint.md, blueprint.json, template workflow files, and docs/agent-handoff.md.

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.

When the setup reveals real follow-up work that is outside the current scope or can be worked on independently, create focused tracker issues so humans or other agents can pick them up later or in parallel. Each issue should include the observed problem, impact, affected files or commands, suggested next steps, and verification already performed. Do not create issues for work you can safely finish in the current task, and never include secrets, tokens, private data, or sensitive logs in public issues. If no issue tracker is available, record the follow-up in docs/agent-handoff.md.

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 Gitea repositories, use a locally set GITEA_TOKEN and GITEA_SERVER_URL 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.