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

### 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/release-checklist.md   -> docs/release-checklist.md
files/security-review.md     -> docs/security-review.md
files/blueprint.md           -> blueprint.md
files/blueprint.json         -> blueprint.json
files/build-gitea.yml        -> .gitea/workflows/build.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. Add a `readme` command.
4. Generate `README.md`.
5. Commit `README.md`, `blueprint.md`, and `blueprint.json`.

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.

### 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, check the pushed workflow run; for private `git.wilkensxl.de` repositories, use a locally set `GITEA_TOKEN` for read-only API status checks when available,
- summarize changed files,
- do not create a release unless explicitly requested.