Add agent support templates and profiles

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/`.
+
 <p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
 
 ## 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.

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
+```
+

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.

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.
 

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
+```
+

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
+

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
+

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
+

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"
+    }
   ]
 }

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"
+          }
+        }
+      }
+    }
+  }
+}
+

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

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
+```
+

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
+```
+

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
+```
+

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/
+```
+

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/
+```
+