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.
