podverse/podverse-documentation-conventions
.cursor/skills/documentation-conventions/SKILL.md
Documentation file naming conventions for the Podverse monorepo. Use when creating or modifying documentation files, README files, or any markdown documentation.
$ install --global
skillsauthnpx skillsauth add podverse/podverse podverse-documentation-conventionsInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Apr 16, 2026, 10:48 PM5.4s1 file scanned
SKILL.md
- name:
- podverse-documentation-conventions
- description:
- Documentation file naming conventions for the Podverse monorepo. Use when creating or modifying documentation files, README files, or any markdown documentation.
Documentation Conventions
Single-Instance Documentation Files
Critical Rules: These files should only exist once in the repository (at root/docs):
- One
README.mdat repository root - One
QUICKSTART.mdindocs/directory
Only one file in the entire repository may be named README (the root README.md). Subdirectories must use descriptive names (e.g. scripts/github/SCRIPTS-GITHUB.md, not README.md).
Directory-Specific Documentation
If a directory needs its own documentation file, name it after the full path from root:
✅ Correct:
apps/api/APPS-API.md
apps/web/APPS-WEB.md
tools/qa/TOOLS-QA.md
infra/docker/ci/INFRA-DOCKER-CI.md
.llm/LLM.md
.llm/plans/LLM-PLANS.md
❌ Incorrect:
apps/api/README.md
apps/web/README.md
tools/qa/README.md
Rationale
Multiple README.md files:
- Create ambiguity in navigation
- Confuse search results
- Break expectations about repository entry points
- Complicate documentation tooling
Naming Pattern
[FULL-PATH-WITH-HYPHENS].md
Convert the directory path to uppercase, replacing slashes with hyphens:
apps/api/→APPS-API.mdpackages/orm/→PACKAGES-ORM.md.llm/plans/active/→LLM-PLANS-ACTIVE.md
Examples
| Directory | Documentation File |
| -------------------------------- | ---------------------------------- |
| Root | README.md (the only one) |
| apps/api/ | APPS-API.md |
| apps/web/ | APPS-WEB.md |
| apps/workers/ | APPS-WORKERS.md |
| apps/management-api/ | APPS-MANAGEMENT-API.md |
| apps/management-web/ | APPS-MANAGEMENT-WEB.md |
| tools/qa/ | TOOLS-QA.md |
| tools/web-perf/ | TOOLS-WEB-PERF.md |
| packages/helpers/ | PACKAGES-HELPERS.md |
| packages/orm/ | PACKAGES-ORM.md |
| infra/docker/ci/ | INFRA-DOCKER-CI.md |
| infra/k8s/ | INFRA-K8S.md |
| scripts/github/ | SCRIPTS-GITHUB.md |
| infra/pipelines/jenkins/alpha/ | INFRA-PIPELINES-JENKINS-ALPHA.md |
| .llm/ | LLM.md |
| .llm/plans/ | LLM-PLANS.md |
Special Cases
Plan directories use a special convention:
.llm/plans/active/feature-name/
├── 00-master-plan.md # Primary: Master overview/index
├── 00-overview.md # Alternative: Overview/guide
├── EXECUTION.md # Parallel execution / agent assignment guide
├── 01-part1.md # Numbered sequential plans
├── 02-part2.md
└── specific-task.md # Descriptive task names
Plan index file naming:
- Primary:
00-master-plan.md- For comprehensive master plans - Alternative:
00-overview.md- For overviews and guides - Legacy:
index.md- Acceptable but less preferred - Never:
README.mdor full-path names likeLLM-PLANS-ACTIVE-FEATURE.md
Plan execution guides:
- Use
EXECUTION.mdfor parallel execution guides, agent assignments, or running instructions - Never:
QUICK-START.mdorQUICKSTART.md(reserved for rootdocs/QUICKSTART.md)
The 00- prefix ensures index files sort first in directory listings.
When Creating Documentation
- Root-level overview? → Update
README.md - Quick start guide? → Update
docs/QUICKSTART.md - Directory-specific docs? → Create
[FULL-PATH].mdin that directory - Specific topic docs? → Use descriptive names (e.g.,
MIGRATIONS.md,TESTING.md) - Plan index/overview? → Use
00-master-plan.mdor00-overview.md - Plan execution guide? → Use
EXECUTION.md(for parallel/agent instructions) - Plan files? → Must go in
.llm/plans/(NOT.cursor/plans/) - History files? → Must go in
.llm/history/(NOT.cursor/history/)
Plan and History Location
Critical: Plans and history are not Cursor-specific and must never be placed in .cursor/ directory.
✅ Correct:
.llm/plans/active/feature-x/
.llm/history/active/feature-y/
❌ Incorrect:
.cursor/plans/active/feature-x/
.cursor/history/active/feature-y/
The .cursor/ directory is for Cursor IDE-specific configuration only (rules, skills, settings).
Migration Note
If you encounter existing README.md files in subdirectories (from legacy structure), rename them following the full-path convention.
Related Skills
podverse/podverse-workers-patterns
documentation
VerifiedTrustedCommunity
Per-job env validation and config patterns for the workers app. Use when adding or changing worker commands, touching workers startup validation, or documenting worker env vars.
4SKILL.mdUpdated Apr 16, 2026
podverse/podverse-web-patterns
development
VerifiedTrustedCommunity
Common patterns and examples for the podverse-web Next.js application
4SKILL.mdUpdated Apr 16, 2026
podverse/time-format-local
tools
VerifiedTrustedCommunity
Ensures client-side time displays use formatDateTimeAbbrev for localized, readable timestamps. Use when rendering dates/times in the UI or when the user mentions time formatting or local timezone display.
4SKILL.mdUpdated Apr 16, 2026
podverse/.cursor/skills/testing-policy
testing
VerifiedTrustedCommunity
--- name: podverse-testing-policy description: Skip test implementation unless the user explicitly asks. Use when a plan or task includes adding unit tests, a test phase, or "Phase 3: Tests". version: 1.0.0 --- # Testing policy — skip tests for now ## When to use - When a plan or task includes adding unit tests, a test phase, or "Phase 3: Tests". - When deciding whether to implement tests for a feature. ## Rules 1. **We are not concerning ourselves with tests at this time.** Skip test imp
4SKILL.mdUpdated Apr 16, 2026