diff --git a/README.md b/README.md index 947db4a..52e9458 100644 --- a/README.md +++ b/README.md @@ -66,6 +66,10 @@ Use only the files that fit the project. For a tiny script repo, `AGENTS.md`, `R | `files/blueprint.json` | `blueprint.json` | | `files/SECURITY.md` | `SECURITY.md` | | `files/CHANGELOG.md` | `CHANGELOG.md` | +| `files/CONTRIBUTING.md` | `CONTRIBUTING.md` | +| `files/gitignore.template` | `.gitignore` | +| `files/agent-handoff.md` | `docs/agent-handoff.md` | +| `files/release-notes.md` | `docs/release-notes.md` | Start with `agent-quickstart.md` when using this kit through Codex. @@ -73,6 +77,8 @@ Start with `agent-quickstart.md` when using this kit through Codex. Agents should read `manifest.json` before copying files. It is the source of truth for target paths, required files, optional files, and placeholder names. +`manifest.schema.json` documents the manifest shape. Stack-specific profile notes live in `profiles/`. +

-----------------------------------------------------

## Placeholders @@ -108,6 +114,7 @@ When applying this kit, an agent should: - read `manifest.json` first, - choose `new-repository.md` or `existing-project.md`, +- read matching `profiles/*.md` guidance after detecting the stack, - check `git status --short` before editing, - preserve unrelated user changes, - use the manifest copy map for target paths, @@ -116,6 +123,7 @@ When applying this kit, an agent should: - keep `AGENTS.md` and `.codex/project.md` aligned, - update `README.md` whenever README blueprint files change, - update security and release docs when release behavior changes, +- update `docs/agent-handoff.md` when work is interrupted, risky, or multi-session, - run `git diff --check` before finishing, - run the cheapest reliable verification command, - poll pushed Gitea workflow runs until success or a concrete blocker. diff --git a/agent-quickstart.md b/agent-quickstart.md index 3db9b76..0e34ed1 100644 --- a/agent-quickstart.md +++ b/agent-quickstart.md @@ -8,6 +8,7 @@ Use this file when you want Codex to apply the repository kit with minimal instr Read manifest.json first. Use its copyMap for file destinations. Use new-repository.md or existing-project.md as the task workflow. +Use matching profiles/*.md guidance after detecting the stack. Check git status before editing. Preserve unrelated user changes. Replace all applicable placeholders and remove non-applicable placeholder sections. @@ -57,6 +58,10 @@ Did you read manifest.json? yes -> use copyMap and placeholders from it no -> read it before editing +Does a stack profile match? + yes -> read the matching profiles/*.md file and adapt commands carefully + no -> continue with universal rules only + Does the project already have README structure? yes -> preserve it; only add blueprint files if useful no -> add blueprint.md and blueprint.json with the rainbow section-line divider @@ -81,6 +86,10 @@ Did release behavior, artifacts, or downloads change? yes -> update docs/release-checklist.md and README downloads/artifacts no -> do not invent release details +Is the work interrupted, risky, or multi-session? + yes -> update docs/agent-handoff.md + no -> no handoff file is required + Is this a private Gitea repo with Actions? yes -> if GITEA_TOKEN is set locally, use it for read-only API checks of repository and workflow-run status no -> use public web/API checks when available @@ -112,6 +121,7 @@ SECURITY.md CHANGELOG.md docs/release-checklist.md docs/security-review.md +docs/agent-handoff.md .gitea/workflows/build.yml ``` @@ -123,3 +133,13 @@ blueprint.json README.md ``` +For stack-specific guidance: + +```text +profiles/node.md +profiles/electron.md +profiles/python.md +profiles/docker.md +profiles/static-site.md +``` + diff --git a/existing-project.md b/existing-project.md index 973a0a3..913dacf 100644 --- a/existing-project.md +++ b/existing-project.md @@ -48,6 +48,8 @@ Identify: - existing release notes or changelog, - security-sensitive behavior. +If a matching stack profile exists in `profiles/`, read it before changing commands, CI, or ignore rules. + ### 2. Add Agent Context Add `AGENTS.md` first. Keep it short and factual. @@ -67,8 +69,11 @@ Add only missing files: ```text SECURITY.md CHANGELOG.md +CONTRIBUTING.md docs/security-review.md docs/release-checklist.md +docs/agent-handoff.md +docs/release-notes.md ``` If equivalent files already exist, update those instead of duplicating them. diff --git a/files/AGENTS.md b/files/AGENTS.md index 3584297..659194a 100644 --- a/files/AGENTS.md +++ b/files/AGENTS.md @@ -7,6 +7,7 @@ PROJECT_NAME: PROJECT_DESCRIPTION ## Repository Rules - Start by reading `manifest.json`, then the workflow file that matches the task: `new-repository.md` for fresh repos or `existing-project.md` for retrofit work. +- Use the matching `profiles/*.md` file when the repository stack is detected. Profiles are guidance, not permission to ignore existing project conventions. - Follow the `manifest.json` copy map for source and target paths. Do not invent alternate locations unless the target repository already has an equivalent convention. - Prefer existing project patterns over new abstractions. - Keep changes scoped to the user's request. @@ -64,5 +65,6 @@ ARTIFACT_NAME - `git diff --check` passes. - The cheapest reliable verification command has been run, or the reason it could not be run is documented. - README, changelog, security review, and release checklist are updated when the change touches release behavior. +- `docs/agent-handoff.md` is updated when work is interrupted, risky, or spans multiple sessions. - Any pushed Gitea workflow has been polled to success or a concrete blocker has been reported. diff --git a/files/CONTRIBUTING.md b/files/CONTRIBUTING.md new file mode 100644 index 0000000..e177c25 --- /dev/null +++ b/files/CONTRIBUTING.md @@ -0,0 +1,48 @@ +# Contributing + +## Working Rules + +- Keep changes scoped to the issue or user request. +- Prefer existing project patterns. +- Do not commit secrets, generated credentials, local `.env` files, or private keys. +- Do not create releases unless explicitly requested. +- Preserve unrelated user changes. + +## Before Committing + +Run the cheapest reliable verification commands for this project: + +```bash +LINT_COMMAND +TEST_COMMAND +BUILD_COMMAND +``` + +Also run: + +```bash +git diff --check +``` + +If a command cannot run, document why in the final response or handoff notes. + +## Pull Requests + +Pull requests should include: + +- summary of changes, +- verification performed, +- known risks or skipped checks, +- artifact/download notes when relevant. + +## Releases + +Before release work, update: + +```text +CHANGELOG.md +docs/release-checklist.md +docs/security-review.md +README.md +``` + diff --git a/files/agent-handoff.md b/files/agent-handoff.md new file mode 100644 index 0000000..4244a40 --- /dev/null +++ b/files/agent-handoff.md @@ -0,0 +1,35 @@ +# Agent Handoff + +Use this file when a task spans multiple sessions, has unresolved follow-up work, or changes release behavior. + +## Current State + +```text +PENDING +``` + +## Changes Made + +- PENDING + +## Verification + +| Check | Result | +| --- | --- | +| `git diff --check` | PENDING | +| `LINT_COMMAND` | PENDING | +| `TEST_COMMAND` | PENDING | +| `BUILD_COMMAND` | PENDING | + +## Open Questions + +- PENDING + +## Next Steps + +- PENDING + +## Risks + +- PENDING + diff --git a/files/gitignore.template b/files/gitignore.template new file mode 100644 index 0000000..a92e800 --- /dev/null +++ b/files/gitignore.template @@ -0,0 +1,46 @@ +# Dependencies +node_modules/ +vendor/ +.venv/ +venv/ +__pycache__/ + +# Build outputs +dist/ +build/ +out/ +release/ +target/ +bin/ +obj/ + +# Logs and temporary files +*.log +*.tmp +*.temp +.cache/ +.turbo/ +.vite/ +.pytest_cache/ + +# Local environment and secrets +.env +.env.* +!.env.example +*.pem +*.key +*.pfx +*.p12 +*.crt +*.cer +*.token +secrets/ + +# OS and editor files +.DS_Store +Thumbs.db +.idea/ +.vscode/ +*.swp +*.swo + diff --git a/files/release-notes.md b/files/release-notes.md new file mode 100644 index 0000000..604ddfc --- /dev/null +++ b/files/release-notes.md @@ -0,0 +1,31 @@ +# PROJECT_NAME PROJECT_VERSION + +## Downloads + +| Variant | Download | +| --- | --- | +| Latest artifact | DOWNLOAD_URL | + +## Highlights + +- PENDING + +## Security + +- Dependency audit: PENDING +- Secret handling: PENDING +- External network calls: PENDING + +## Verification + +| Check | Result | +| --- | --- | +| `LINT_COMMAND` | PENDING | +| `TEST_COMMAND` | PENDING | +| `BUILD_COMMAND` | PENDING | +| Artifact download | PENDING | + +## Notes + +PENDING + diff --git a/manifest.json b/manifest.json index 3c92a7f..e1af26a 100644 --- a/manifest.json +++ b/manifest.json @@ -26,6 +26,7 @@ "existingProject": "existing-project.md", "quickstart": "agent-quickstart.md" }, + "schema": "manifest.schema.json", "copyMap": [ { "source": "files/AGENTS.md", @@ -47,6 +48,26 @@ "target": "CHANGELOG.md", "required": false }, + { + "source": "files/CONTRIBUTING.md", + "target": "CONTRIBUTING.md", + "required": false + }, + { + "source": "files/gitignore.template", + "target": ".gitignore", + "required": false + }, + { + "source": "files/agent-handoff.md", + "target": "docs/agent-handoff.md", + "required": false + }, + { + "source": "files/release-notes.md", + "target": "docs/release-notes.md", + "required": false + }, { "source": "files/release-checklist.md", "target": "docs/release-checklist.md", @@ -93,5 +114,27 @@ "DEV_COMMAND", "PACKAGE_MANAGER", "PROJECT_VERSION" + ], + "profiles": [ + { + "name": "node", + "path": "profiles/node.md" + }, + { + "name": "electron", + "path": "profiles/electron.md" + }, + { + "name": "python", + "path": "profiles/python.md" + }, + { + "name": "docker", + "path": "profiles/docker.md" + }, + { + "name": "static-site", + "path": "profiles/static-site.md" + } ] } diff --git a/manifest.schema.json b/manifest.schema.json new file mode 100644 index 0000000..353108a --- /dev/null +++ b/manifest.schema.json @@ -0,0 +1,93 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "Codex Agent Repository Kit Manifest", + "type": "object", + "required": ["name", "version", "description", "workflows", "copyMap", "placeholders"], + "properties": { + "name": { + "type": "string" + }, + "version": { + "type": "string" + }, + "description": { + "type": "string" + }, + "agentResponsibilities": { + "type": "array", + "items": { + "type": "string" + } + }, + "readmeDivider": { + "type": "object", + "required": ["templateName", "source", "usage"], + "properties": { + "templateName": { + "type": "string" + }, + "source": { + "type": "string" + }, + "usage": { + "type": "string" + } + } + }, + "workflows": { + "type": "object", + "required": ["newRepository", "existingProject", "quickstart"], + "properties": { + "newRepository": { + "type": "string" + }, + "existingProject": { + "type": "string" + }, + "quickstart": { + "type": "string" + } + } + }, + "copyMap": { + "type": "array", + "items": { + "type": "object", + "required": ["source", "target", "required"], + "properties": { + "source": { + "type": "string" + }, + "target": { + "type": "string" + }, + "required": { + "type": "boolean" + } + } + } + }, + "placeholders": { + "type": "array", + "items": { + "type": "string" + } + }, + "profiles": { + "type": "array", + "items": { + "type": "object", + "required": ["name", "path"], + "properties": { + "name": { + "type": "string" + }, + "path": { + "type": "string" + } + } + } + } + } +} + diff --git a/new-repository.md b/new-repository.md index 710dbd5..03a888b 100644 --- a/new-repository.md +++ b/new-repository.md @@ -30,6 +30,8 @@ Identify: - 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: @@ -39,8 +41,12 @@ 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 diff --git a/profiles/docker.md b/profiles/docker.md new file mode 100644 index 0000000..87ffbc0 --- /dev/null +++ b/profiles/docker.md @@ -0,0 +1,36 @@ +# Docker Profile + +Use when the repository has `Dockerfile`, `compose.yml`, or deployment container artifacts. + +## Checks + +Look for: + +- secrets copied into images, +- `.env` files committed, +- broad build contexts, +- unpinned base images, +- root-only runtime when avoidable, +- exposed ports documented in README. + +## Commands + +Common placeholders: + +```text +BUILD_COMMAND = docker build -t PROJECT_NAME . +TEST_COMMAND = docker compose config +AUDIT_COMMAND = docker scout cves PROJECT_NAME +``` + +Use only commands that are available in the target environment. + +## Ignore Additions + +```text +.env +.env.* +!.env.example +docker-compose.override.yml +``` + diff --git a/profiles/electron.md b/profiles/electron.md new file mode 100644 index 0000000..798c36e --- /dev/null +++ b/profiles/electron.md @@ -0,0 +1,43 @@ +# Electron Profile + +Use when the repository builds an Electron desktop app. + +## Security Expectations + +Check for: + +```text +contextIsolation: true +nodeIntegration: false +sandbox: true when compatible +webSecurity: true +allowRunningInsecureContent: false +``` + +Avoid: + +```text +eval +shell.openExternal without allowlist +unsafe navigation +unvalidated IPC writes +``` + +## Release Notes + +Document: + +- installer artifact, +- portable artifact if available, +- signing status, +- SmartScreen/Defender limitations, +- whether secrets or user files stay local. + +## Common Artifacts + +```text +release/*.exe +release/*.blockmap +release/*.yml +``` + diff --git a/profiles/node.md b/profiles/node.md new file mode 100644 index 0000000..88a8316 --- /dev/null +++ b/profiles/node.md @@ -0,0 +1,42 @@ +# Node Profile + +Use when the repository has `package.json`. + +## Detection + +Common files: + +```text +package.json +package-lock.json +pnpm-lock.yaml +yarn.lock +tsconfig.json +vite.config.* +``` + +## Commands + +Prefer existing scripts. Common defaults: + +```text +INSTALL_COMMAND = npm install +LINT_COMMAND = npm run lint +TEST_COMMAND = npm test +BUILD_COMMAND = npm run build +AUDIT_COMMAND = npm audit --omit=dev --audit-level=high +README_COMMAND = npm run readme +``` + +If scripts are missing, document `PENDING` instead of inventing commands. + +## Ignore Additions + +```text +node_modules/ +dist/ +build/ +coverage/ +*.log +``` + diff --git a/profiles/python.md b/profiles/python.md new file mode 100644 index 0000000..f44dca8 --- /dev/null +++ b/profiles/python.md @@ -0,0 +1,36 @@ +# Python Profile + +Use when the repository has `pyproject.toml`, `requirements.txt`, or Python source files. + +## Commands + +Prefer existing tooling. Common examples: + +```text +INSTALL_COMMAND = python -m pip install -r requirements.txt +LINT_COMMAND = ruff check . +TEST_COMMAND = pytest +BUILD_COMMAND = python -m build +AUDIT_COMMAND = pip-audit +``` + +If the project uses `uv`, prefer: + +```text +INSTALL_COMMAND = uv sync +TEST_COMMAND = uv run pytest +AUDIT_COMMAND = uv pip audit +``` + +## Ignore Additions + +```text +.venv/ +venv/ +__pycache__/ +.pytest_cache/ +dist/ +build/ +*.egg-info/ +``` + diff --git a/profiles/static-site.md b/profiles/static-site.md new file mode 100644 index 0000000..5f7a858 --- /dev/null +++ b/profiles/static-site.md @@ -0,0 +1,36 @@ +# Static Site Profile + +Use when the repository produces static HTML/CSS/JS output. + +## Checks + +Look for: + +- broken asset paths, +- missing responsive viewport, +- inaccessible contrast, +- large unoptimized images, +- external scripts without a clear reason, +- generated output directory. + +## Commands + +Common examples: + +```text +INSTALL_COMMAND = npm install +DEV_COMMAND = npm run dev +LINT_COMMAND = npm run lint +BUILD_COMMAND = npm run build +``` + +## Artifacts + +Common output directories: + +```text +dist/ +build/ +public/ +``` +