TL;DR
Use this skill when a project needs durable FE/BE/DevOps/Admin/QA context. Generate .codex/project-docs/ once, then keep role docs updated as code changes.
Codex Role Docs
Activation
- Activate on
$role-docs, $init-docs, or $check-docs.
- Activate when the user asks for project docs, role docs, technical documentation, architecture notes, API docs, UI/UX docs, runbooks, or durable context.
- Activate during long-running projects where micro-context can be lost across sessions.
- Auto-use with agent personas when a role-owned file changes.
Core Rule
Role docs are project-local artifacts, not always-loaded context. Read only the role docs needed for the current task, then update the same docs before completion when code behavior, contracts, architecture, UI patterns, deployment, admin flows, or tests changed.
Commands
- Initialize docs:
init_role_docs.py --project-root <path>
- Update one doc:
update_role_docs.py --project-root <path> --role <role> --doc <doc-id> --summary <text> --files <csv>
- Check impact:
check_role_docs.py --project-root <path> --changed-files <csv>
- Rebuild index:
build_role_docs_index.py --project-root <path>
- See
skills/.system/REGISTRY.md for full script paths.
Role Ownership
| Role |
Owns |
frontend-specialist |
frontend/FE-*, admin UI flows, dashboards, reports |
backend-specialist |
backend/BE-*, admin permissions, contracts, data management |
devops-engineer |
devops/DO-* |
test-engineer |
qa/QA-* |
security-auditor |
auth/security, permissions, audit-log docs |
planner |
project brief, ADR template, admin scope |
Update Discipline
- Before editing, check whether relevant docs exist under
.codex/project-docs/.
- If missing and the task is project setup or planning, run
$init-docs.
- After code changes, run
$check-docs or map changed files manually.
- Update only the docs owned by the active agent's role.
- Keep entries factual: decision, source files, constraints, risks, verification.
- Do not block completion only because docs are missing unless the user explicitly made docs mandatory.
Generated Structure
PROJECT-BRIEF.mdindex.jsondecisions/ADR-0001-template.mdfrontend/FE-*.mdbackend/BE-*.mddevops/DO-*.mdadmin/AD-*.mdqa/QA-*.md
Resources
templates/role_docs_manifest.json: canonical role docs, owners, and doc metadata.templates/project-brief-template.md: project-level context template.templates/role-doc-template.md: shared role-document template.templates/adr-template.md: decision record template.
1---2name: codex-role-docs3description: Use for role-scoped FE/BE/DevOps/Admin/QA project docs under .codex/project-docs to preserve micro-context across long projects.4---56## TL;DR7Use this skill when a project needs durable FE/BE/DevOps/Admin/QA context. Generate `.codex/project-docs/` once, then keep role docs updated as code changes.89# Codex Role Docs1011## Activation12131. Activate on `$role-docs`, `$init-docs`, or `$check-docs`.142. Activate when the user asks for project docs, role docs, technical documentation, architecture notes, API docs, UI/UX docs, runbooks, or durable context.153. Activate during long-running projects where micro-context can be lost across sessions.164. Auto-use with agent personas when a role-owned file changes.1718## Core Rule1920Role docs are project-local artifacts, not always-loaded context. Read only the role docs needed for the current task, then update the same docs before completion when code behavior, contracts, architecture, UI patterns, deployment, admin flows, or tests changed.2122## Commands2324- Initialize docs: `init_role_docs.py --project-root <path>`25- Update one doc: `update_role_docs.py --project-root <path> --role <role> --doc <doc-id> --summary <text> --files <csv>`26- Check impact: `check_role_docs.py --project-root <path> --changed-files <csv>`27- Rebuild index: `build_role_docs_index.py --project-root <path>`28- See `skills/.system/REGISTRY.md` for full script paths.2930## Role Ownership3132| Role | Owns |33| --- | --- |34| `frontend-specialist` | `frontend/FE-*`, admin UI flows, dashboards, reports |35| `backend-specialist` | `backend/BE-*`, admin permissions, contracts, data management |36| `devops-engineer` | `devops/DO-*` |37| `test-engineer` | `qa/QA-*` |38| `security-auditor` | auth/security, permissions, audit-log docs |39| `planner` | project brief, ADR template, admin scope |4041## Update Discipline42431. Before editing, check whether relevant docs exist under `.codex/project-docs/`.442. If missing and the task is project setup or planning, run `$init-docs`.453. After code changes, run `$check-docs` or map changed files manually.464. Update only the docs owned by the active agent's role.475. Keep entries factual: decision, source files, constraints, risks, verification.486. Do not block completion only because docs are missing unless the user explicitly made docs mandatory.4950## Generated Structure5152- `PROJECT-BRIEF.md`53- `index.json`54- `decisions/ADR-0001-template.md`55- `frontend/FE-*.md`56- `backend/BE-*.md`57- `devops/DO-*.md`58- `admin/AD-*.md`59- `qa/QA-*.md`6061## Resources6263- `templates/role_docs_manifest.json`: canonical role docs, owners, and doc metadata.64- `templates/project-brief-template.md`: project-level context template.65- `templates/role-doc-template.md`: shared role-document template.66- `templates/adr-template.md`: decision record template.
Bang-isme