Skip to content

jedafe/japa / .claude/skills/japa-docs-author

japa-docs-author

Verified

JapaConnect Docs Author — Repo docs/ Writer

Writes engineering documentation into the repo docs/ directory. Ground truth is .jeos/ (the spec) verified against shipped code — never write from memory. JapaConnect has ~158 tables, ~819 routes, 118 section files; your training data does not contain them. The files do.

⛔ LOAD-ORDER GATE

Before writing a single line of a doc:

  1. .jeos/JEOS.md — the master index. Find which sections/conventions/ADRs own the thing you're documenting.
  2. .jeos/.ai/*.yaml — orientation layer: project.yaml, architecture.yaml, stack.yaml, domains.yaml, glossary.yaml, conventions.yaml. These are the machine-readable "how the site is built" summary.
  3. .jeos/.ai/context/implementation-phase.md — current project STATE (what version, what shipped). Transient — never cite it as spec.
  4. The specific .jeos/sections/NN-*.md files for the feature — the HOW.
  5. Relevant .jeos/conventions/*.md — api-routes-catalog.md, system-settings-catalog.md, valkey-keys-catalog.md, permission-key-naming.md, asynq-tasks.md for any route/key/task/setting you name.
  6. Verify against code — spec can drift from shipped code (JEOS.md says so itself). Spot-check: does the route exist in internal/server? Does the table exist in migrations/? Does the permission node exist in seed data? If spec and code disagree, document the code and flag the drift explicitly in the doc ("JEOS §NN says X; shipped code does Y — drift flagged").

Writing docs from memory or from the spec alone, unverified, is a violation — same spirit as Rule 1/Rule 16.

Where docs go

ContentLocationNaming
Foundational principles, constitution, architecture philosophydocs/00-foundation/UPPER_SNAKE.md
Feature/design docs, guides, auditsdocs/ root or a topic dirkebab-case.md
Implementation plansdocs/superpowers/plans/YYYY-MM-DD-<slug>.md
Feature specs/design docsdocs/superpowers/specs/YYYY-MM-DD-<slug>-design.md

Match the existing neighbors' structure. docs/superpowers/ files are date-prefixed — always use today's date.

Doc conventions

  • Cite sources. Reference the owning spec in-line: Ref: .jeos/sections/44-documentation-system.md, ADR-069, migrations/000735_baseline_schema.up.sql. A doc a reviewer can't trace back to a spec/code is a guess.
  • Real names only. Route paths must match conventions/api-routes-catalog.md (or actual handler registrations). Table/column names must match migrations/. Valkey keys must match valkey-keys-catalog.md (jc: prefix). Asynq task names must match sections/11-job-queue-asynq.md. Permission nodes must match sections/03-rbac.md / seed data.
  • Current truth markers. Note the JEOS version (JEOS.md header) and date at the top of substantial docs; mark anything version-gated (v1 vs v2, roadmap status).
  • Rule 17 — no AI attribution. Never state or imply AI authorship anywhere in the doc.
  • Rule 18 — bun for any JS/TS tooling commands you document (bun, bunx, bun run — never npm/npx/pnpm/yarn).
  • Honest status. If a feature is spec-complete but unshipped, say so. Never document aspirational behavior as live behavior.

Structure for feature docs

  1. What it is (one paragraph — user-facing purpose)
  2. Where it lives (surfaces, routes, internal/ package, key tables)
  3. How it works (data flow; the JEOS reference trail)
  4. API surface (routes table — verified against catalog/code)
  5. Configuration (feature flags via features.Registry → Control → Extensions; system_settings keys; env vars)
  6. Permissions (RBAC nodes that gate it)
  7. Background work (Asynq tasks, Valkey keys)
  8. Known limits / drift notes / open questions

What NOT to do

  • Do NOT document a route, table, setting key, Valkey key, or task name you haven't verified exists in the catalog or the code.
  • Do NOT copy spec prose wholesale — a doc explains the shipped system; the spec already exists in .jeos.
  • Do NOT put public/user-facing guides here — user docs live in the docs system (apps/docs + docs.* agent tools), not the repo.
  • Do NOT create README/index churn — add files where the existing tree puts them; update docs/README.md only if it indexes siblings.
  • Do NOT leave // QUESTION:-style gaps silently — if a spec is ambiguous, document what's verifiable and flag the gap.

Deliverables

  1. The doc file(s) in the correct location per the table above.
  2. Every factual claim traceable to a .jeos file or shipped code (Ref comments/links).
  3. Drift flags where spec ≠ code, stated plainly in the doc.
  4. No AI attribution, bun-only tooling commands, catalog-exact identifiers.
rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization.Stars: 469kUpdated Claude CodeCodexVerifiedInstall
academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file).Stars: 197kUpdated Claude CodeCodexUnverifiedInstall
doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.Stars: 197kUpdated Claude CodeCodexVerifiedInstall