Skip to content
Skills Library
Programming · Writing

codex-role-docs

/codex-role-docs

Use for role-scoped FE/BE/DevOps/Admin/QA project docs under .codex/project-docs to preserve micro-context across long projects.

Licence
MIT
Last repository change
23.10.2026

Assessment and security

90/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content25 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
10
Scripts
4
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 23.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 4 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: scripts/build_role_docs_index.py, scripts/check_role_docs.py, scripts/init_role_docs.py, scripts/update_role_docs.py

What it does and when to use it

Use for role-scoped FE/BE/DevOps/Admin/QA project docs under .codex/project-docs to preserve micro-context across long projects.

Original author description

Use for role-scoped FE/BE/DevOps/Admin/QA project docs under .codex/project-docs to preserve micro-context across long projects.

How it works

  1. TL;DR
  2. Activation
  3. Core Rule
  4. Commands
  5. Role Ownership
  6. Update Discipline
  7. Generated Structure
  8. Resources
Original SKILL.md headings · 62 lines, 471 words
SKILL.md preview
---
name: codex-role-docs
description: Use for role-scoped FE/BE/DevOps/Admin/QA project docs under .codex/project-docs to preserve micro-context across long projects.
load_priority: on-demand
---

## TL;DR
Use this skill when a project needs durable FE/BE/DevOps/Admin/QA context. Initialize only the project brief by default; create role folders for the roles this project actually needs, then keep those docs current as code changes.

# Codex Role Docs

## Activation

1. Activate on `$role-docs`, `$init-docs`, or `$check-docs`.
2. Activate when the user asks for project docs, role docs, technical documentation, architecture notes, API docs, UI/UX docs, runbooks, or durable context.
3. Activate during long-running projects where micro-context can be lost across sessions.
4. Auto-use with agent personas when a role-owned file changes.

## Core Rule

Role docs are Tier 4 (L3) domain micro-context inside the Unified Project Memory Architecture (`../codex-project-memory/references/unified-memory-architecture.md`), not always-loaded context. Read only the role docs needed for the current task, honor Tier 3 normative specs/ADRs (`SPEC.md`, `DESIGN.md`, `.codex/decisions/`), and update the active role's docs before completion when code behavior, contracts, architecture, UI patterns, deployment, admin flows, or tests changed.

## Commands

- Initialize minimal docs: `init_role_docs.py --project-root <path>` (project brief + ADR template only)
- Initialize fullstack preset (FE + BE + DevOps + QA): `init_role_docs.py --project-root <path> --roles fullstack`
- Initialize MVP preset (FE + BE + QA): `init_role_docs.py --project-root <path> --roles mvp`
- Initialize selected roles: `init_role_docs.py --project-root <path> --roles frontend,qa`
- Initialize every role only when needed: `init_role_docs.py --project-root <path> --roles all`
- Update one doc (including decisions, SILC contracts, verification, stage, and population): `update_role_docs.py --project-root <path> --role <role> --doc <doc-id> --summary <text> --files <csv> --decision <text> --contract <text> --verification <text> --stage "<stage>" --population populated`
- Check impact & unpopulated stubs: `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

1. Before editing, check whether relevant docs exist under `.codex/project-docs/`.
2. If missing and the task is project setup or planning, run `$init-docs`.
3. After code changes, run `$check-docs` or map changed files manually.
4. Update only the docs owned by the active agent's role.
5. Keep entries factual: decision, source files, constraints, risks, verification.
6. Do not block completion only because docs are missing unless the user explicitly made docs mandatory.

## Generated Structure

- Always: `PROJECT-BRIEF.md` and `decisions/ADR-0001-template.md`.
- On request: `frontend/FE-*.md`, `backend/BE-*.md`, `devops/DO-*.md`, `admin/AD-*.md`, and/or `qa/QA-*.md` for the selected roles.
- `index.json` is created only when the index builder runs.

## 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.
Files in this package (10)
  • SKILL.md 4 KB
  • agents/openai.yaml 1 KB
  • scripts/build_role_docs_index.py 5 KB
  • scripts/check_role_docs.py 12 KB
  • scripts/init_role_docs.py 10 KB
  • scripts/update_role_docs.py 8 KB
  • templates/adr-template.md 1 KB
  • templates/project-brief-template.md 3 KB
  • templates/role-doc-template.md 1 KB
  • templates/role_docs_manifest.json 10 KB

Versions

The database has no other skills named codex-role-docs.

Database snapshot: 13.11.2026 · package version af17f02c6bbc (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100specialist-agents
    Use when you need specialist role guidance for architecture, engineering, QA, security, docs, devops, service design, UX, UI design, UI implementation, or industrial design in a Codex session or delegated subagent.
  • 100generating-project-docs
    Use when creating, refreshing, or updating project-level documentation — README.md, ARCHITECTURE.md, STRUCTURE.md, or scoped section updates
  • 80vc:docs
    Use when you need to analyze a codebase and initialize, update, or summarize project documentation.
  • 100project-docs
    Generate project documentation from codebase analysis — ARCHITECTURE.md, API_ENDPOINTS.md, DATABASE_SCHEMA.md. Reads source code, schema files, routes, and config to produce accurate, structured docs. Use when starting a project, onboarding contributors, or when docs are missing…
  • 100project-docs
    Use when looking for project-specific documentation. Knows which docs exist in agents/reference/docs/ and agents/settings/contexts/ and maps work areas to relevant docs.
  • 100writing-docs
    Write, audit or update a project's docs from its source code. User docs (quickstart, install, configuration, a page per feature) and maintainer docs (architecture, data model, invariants), as plain Markdown or for a docs framework such as Starlight or MkDocs. Use for "write the…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.