177 lines
4.5 KiB
Markdown
177 lines
4.5 KiB
Markdown
# 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
|
|
```
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
### 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.
|
|
|