pinq-doq

PinqPonq's shared AI knowledge hub: coding rules, reusable skills, code-generation scripts, and deep references for every project (mobile + backend).

Layout

pinq-doq/
  rules/          → COPIED into a consumer's .claude/rules/   (auto-loaded, scoped by paths:)
    common.md                 always-on; carries a stack pointer to the files below
    kotlin-architecture.md    paths: ['**/*.kt','**/*.kts'] — Clean Arch, MVI, shared module
    kotlin-naming.md          paths: ['**/*.kt','**/*.kts']
    kotlin-conventions.md     paths: ['**/*.kt','**/*.kts'] — Compose, style, null-safety, DI
    kotlin-deveng-core.md     paths: ['**/*.kt','**/*.kts'] — cites references/kotlin/deveng-core-reference.md
    kotlin-testing.md         paths: ['**/*.kt','**/*.kts'] — test stack, what every change must test, device proof
    dotnet-conventions.md     paths: ['**/*.cs','**/*.csproj','**/*.sln']
    ui-proof-review.md        paths: ['**/*.kt','**/*.ts', …, 'maestro/**','e2e/**'] — independent review of UI proof recordings, checklist
    web-testing.md            paths: ['**/*.ts','**/*.tsx','**/*.js','**/*.jsx', …] — web end-to-end proof with Playwright
  skills/         → COPIED into a consumer's .claude/skills/  (intent-discovered)
    add-feature/                orchestrates a whole feature: presentation + API, then connects them
    presentation-scaffold/      presentation layer via scripts/ (screen/MVI, nav, components, strings)
    api-endpoint-integration/   backend of an endpoint via scripts/ (data → domain → use case → DI)
    kmp-theme-setup/            colors / typography / AppTheme wiring for deveng-core-kmp
    code-review/                review a diff against rules/ (no external services)
    handoff/                    write a curated session checkpoint to .claude/handoffs/ (gitignored)
    release-notes/              App Store + Play release notes from the commits since the last release
    executive-mail-review/      check a draft email against the executive mail standard + writing guide (report only)
    vault-config-setup/         move a .NET project's secrets and per-reader settings into Vault records (via scripts/vault_config.py)
    vault-dev-setup/            get a developer machine ready to run a project that already reads from Vault (vault_config.py check)
    r2-upload-setup/            photo and video upload through Cloudflare R2: bucket, Vault, .NET backend, KMP client, checks
    new-product/                start a new product from kmp-app-template + the backend template (via scripts/new_product.py)
  scripts/        → NOT copied; run in place via CLI (KMP code generators, deliver.py the copy helper, vault_config.py and storage_keys.py for Vault, new_product.py for templates)
    verification/   build, test and mutation wrappers behind the pin-test subagent (usable without the runner)
  references/     → NOT copied; read on demand by path
    kotlin/
      deveng-core-reference.md  full deveng-core-kmp API map
      deep dives: architecture.md, data-layer.md, mvi-pattern.md, viewmodel-patterns.md,
      naming.md, error-handling.md, fake-data.md, formatting.md, shared-module.md, testing.md
    maestro/
      maestro-kit.md            Maestro scripts + subflows to copy into an app (no product values)
    dotnet/
      vault-configuration.md    the Vault configuration standard: readers, record layout, tokens, pitfalls
      vault-cli-setup.md        developer machine setup: install the CLI, log in, troubleshoot
    web/
      e2e-playwright.md         Playwright setup for web projects: config, stored sign-in, run-flow script, examples
    templates/
      new-product-starter.md    mobile and backend templates, template.json manifest, product file
    widget/
      widget-setup.md           home screen widget setup with deveng-widget + production lessons
      ios/                      Swift templates for the widget extension and the app's reload helper
  context/        → NOT copied; read on demand by skills (organizational knowledge)
    agent/          knowledge pack of the Pinq Center agent: knowledge-index.md (topic → document table the agent searches), system map, task rules, troubleshooting
    projects/
      deveng-group-proje-portfoyu.md   project portfolio, business model, inter-project relations
    team/           (add members.md here for assignee suggestions)
    tools/          (add github-workflow.md here for GitHub Projects conventions)
  tasks/          integrate.md (first-time setup), update.md (adopt newer standards), install-runner.md (task runner on a machine)
  runner/         → NOT copied; the pinqloq task runner (skill, agents; the panel is pinqponq/pinqponq-agents), linked into ~/.claude per machine — see runner/README.md
  meta/           authoring-guide.md (write a skill), document-writing-guide.md (write a document, Turkish), contributing.md (extend pinq-doq)
  README.md, CLAUDE.md   repo docs — never delivered into consumers

Using the skills

You don't run a command to use a skill. After integrate/update copies them into .claude/skills/, Claude discovers them by intent: describe what you want in plain language and Claude matches it to a skill's description. You can also force one with /<skill-name> (e.g. /code-review).

Say something like…	Triggers
"review my changes", "check against standards", "review before PR"	code-review
"add a new feature", "build a screen and its endpoint"	add-feature
"scaffold a screen", "add a screen / component / strings"	presentation-scaffold
"integrate a standalone endpoint", "add this API to a feature"	api-endpoint-integration
"set up theming / colors / typography"	kmp-theme-setup
"create a handoff", "park this", "checkpoint before /clear"	handoff
"create a task", "add this to GitHub", "task aç", "open a task on the board"	create-task
"draft a task for", "help me write this ticket", "kime atasam" (draft only, no create)	draft-task
"mailimi kontrol et", "bu maili gönderebilir miyim", "check my email before sending"	executive-mail-review
"move secrets to Vault", "read appsettings from Vault", "set up Vault configuration for this project"	vault-config-setup
"vault hesabım var, projeyi ayağa kaldırmak istiyorum", "run this project locally", "vault login", "Vault rejected the token"	vault-dev-setup
"add photo upload", "video upload", "R2 upload", "presign", "foto ve video yükleme"	r2-upload-setup

The full, authoritative trigger list for each skill lives in the description at the top of its SKILL.md — that's the single source of truth, so this table stays a quick taste, not a copy to keep in sync.

Delivery model — copy, not live submodule

The repo is mounted once in a consumer at a neutral path (.pinq-doq/). From there:

• rules/ and skills/ are copied into the consumer's .claude/ and committed (plus a .claude/.pinq-doq-version stamp recording the source SHA).
• references/ and scripts/ are used in place from the .pinq-doq/ mount.

Why copy instead of mounting the rules straight at .claude/rules? Some teammates are on Windows (no symlinks), and committing the copies means the rules travel with the repo on a fresh clone — no submodule update --init needed to get them. The version stamp makes copy-staleness detectable.

Setup

Tell Claude, inside your project:

Install pinq-doq from https://github.com/pinqponq/pinqdoq — add it as a git submodule at .pinq-doq, then follow .pinq-doq/tasks/integrate.md.

That one sentence is all a teammate needs — nothing to copy or hand over. Claude adds the submodule, then runs tasks/integrate.md: copies rules/+skills/ into .claude/, writes the .claude/.pinq-doq-version stamp, wires CLAUDE.md, and commits. (Prefer to do it by hand? The same steps are in that file.)

Updating

When pinq-doq changes and you want the newer standards, say to Claude inside your project:

update rules

Claude runs tasks/update.md: pulls the latest pinq-doq, re-copies rules/+skills/ via .pinq-doq/scripts/deliver.py (overwriting changed files and pruning stale/renamed ones), refreshes the version stamp, and commits. It also auto-converts a project still on the old layout (submodule mounted at .claude/rules) to the new copy model. Manual steps are in the same file.

How rules load

Claude Code auto-loads every .md directly under a project's .claude/rules/ into every session at startup. Because integrate/update copy pinq-doq/rules/ into .claude/rules/, those rule files — and only those — auto-load in consumers. Control loading per file with paths: YAML frontmatter:

• Universal rules (common.md) — no frontmatter, so they always load. common.md also carries a short pointer to the stack-specific files so Claude knows they exist before one triggers.

• Stack-specific rules (kotlin-architecture.md, kotlin-naming.md, kotlin-conventions.md, kotlin-deveng-core.md, kotlin-testing.md, dotnet-conventions.md, web-testing.md, ui-proof-review.md) — scoped with paths: so they load only when Claude touches a matching file (Kotlin rules stay out of a C# project, and vice versa):

  ---
  paths: ['**/*.kt', '**/*.kts']
  ---
  

skills/, scripts/, references/, and the repo's own README.md/CLAUDE.md are not copied into .claude/rules/, so they never auto-load — skills are intent-discovered from .claude/skills/, and scripts/references are used on demand from the .pinq-doq/ mount.

Two gotchas when adding rules:

• A new stack-specific rule without paths: loads into every consumer (including unrelated stacks) — scope it.
• Do not @import a paths-scoped rule from a consumer's CLAUDE.md; @import force-loads it and defeats the scope. Let auto-load handle it.

Contributing

Changes here affect all projects. See meta/contributing.md for how to add a rule, reference, skill, script, or a whole new stack. Open a PR and get team review before merging.