docs(copilot): add canonical Quirk prompt pack

prompt-packs/quirk/Quirk-GitHub-Prompt-System.md

@@ -0,0 +1,55 @@
+# Quirk GitHub Prompt System
+
+## Purpose
+
+This is the human-readable source of truth for the Quirk GitHub Prompt Pack: eleven reusable Copilot workflows that turn repository work into bounded actions with evidence.
+
+## Architecture
+
+| Layer | Best format | Responsibility |
+| --- | --- | --- |
+| Organization doctrine | Organization instructions | Standards shared across Quirk Systems |
+| Repository doctrine | `.github/copilot-instructions.md` or `AGENTS.md` | Architecture, commands, constraints, and conventions |
+| Repeatable task | `.github/prompts/*.prompt.md` | Manually invoked workflows |
+| Persistent specialist | `.github/agents/*.agent.md` | Focused role, tools, and operating method |
+| Reusable capability | `.github/skills/*/SKILL.md` | On-demand instructions, scripts, examples, and resources |
+
+## Eleven Moves
+
+1. **Orient** — understand the repository before acting.
+2. **Build** — implement the smallest coherent feature with tests.
+3. **Review** — prioritize real defects and issue an explicit verdict.
+4. **Poke Holes** — attack assumptions before implementation hardens them.
+5. **Fix CI** — trace the earliest meaningful failure and prove the repair.
+6. **Dependencies** — inspect direct upgrades, transitive churn, and migration risk.
+7. **Architecture** — compare viable options and record the decision.
+8. **Core Contract** — protect canonical, runtime, and projection boundaries.
+9. **Security Pass** — trace inputs, identity, authority, secrets, and side effects.
+10. **Ship** — produce a clean, verified, reviewer-ready change.
+11. **Compound** — extract the reusable capability proven by completed work.
+
+## Prompt Spine
+
+Every serious Quirk prompt should establish:
+
+1. **Context** — what repository state and instructions govern the task?
+2. **Outcome** — what observable behavior must become true?
+3. **Constraints** — what must remain true while accomplishing it?
+4. **Evidence** — what code, tests, logs, schemas, or documentation support each claim?
+5. **Action** — what is the smallest coherent intervention?
+6. **Verification** — what proves the outcome actually works?
+7. **Risk** — what could still fail, and under what conditions?
+8. **Residue** — what remains unknown, deliberately excluded, or dependent on human authority?
+
+## Quality Gate
+
+- A plausible answer is not evidence.
+- A green check is not proof of complete behavior.
+- A large diff is not proof of progress.
+- A recommendation without tradeoffs is incomplete.
+- An agent must distinguish verified facts, reasonable inference, and unresolved uncertainty.
+- No workflow may claim success without reporting the verification performed and the checks not run.
+
+## Installation
+
+Copy the eleven files from `prompts/` into `.github/prompts/` in any target repository. Keep repo-specific facts out of the shared prompt bodies; place them in repository instructions so the prompts remain portable.

prompt-packs/quirk/README.md

@@ -0,0 +1,40 @@
+# Quirk GitHub Prompt Pack
+
+Eleven reusable GitHub Copilot prompt files for evidence-backed Quirk Systems engineering.
+
+## Install
+
+Copy the files in `prompts/` into a repository's `.github/prompts/` directory. Invoke them in Copilot Chat with `/quirk-orient`, `/quirk-build`, or the corresponding prompt name.
+
+Prompt files define repeatable tasks. Keep repository-wide standards in `.github/copilot-instructions.md` or `AGENTS.md`, and use custom agents for persistent specialist behavior.
+
+## Prompt Map
+
+| Prompt | Use |
+| --- | --- |
+| `quirk-orient` | Map an unfamiliar repository without changing it |
+| `quirk-build` | Implement a bounded feature with proof |
+| `quirk-review` | Produce a decision-grade code review |
+| `quirk-poke-holes` | Adversarially test a plan or architecture |
+| `quirk-fix-ci` | Diagnose and repair a failing check |
+| `quirk-deps` | Assess dependency and lockfile risk |
+| `quirk-architecture` | Write an evidence-backed architecture decision |
+| `quirk-core-contract` | Protect canonical, runtime, and projection boundaries |
+| `quirk-security-pass` | Trace credible security failures |
+| `quirk-ship` | Prepare a reviewer-ready pull request |
+| `quirk-compound` | Extract reusable capability from finished work |
+
+## Quirk Prompt Spine
+
+Every prompt moves through:
+
+1. **Context** — governing repository state and instructions
+2. **Outcome** — observable behavior that must become true
+3. **Constraints** — properties that must remain true
+4. **Evidence** — code, tests, logs, schemas, or documentation supporting claims
+5. **Action** — smallest coherent intervention
+6. **Verification** — proof that the outcome works
+7. **Risk** — remaining failure conditions
+8. **Residue** — unknowns, exclusions, and human decisions
+
+The governing rule: do not claim success without evidence.

prompt-packs/quirk/prompts/quirk-architecture.prompt.md

@@ -0,0 +1,35 @@
+---
+name: quirk-architecture
+description: Create an evidence-backed architecture decision
+agent: plan
+argument-hint: problem or proposed architectural change
+---
+
+Analyze the architectural decision using this repository as the primary evidence.
+
+Define:
+
+- decision to be made
+- forces and constraints
+- current architecture
+- desired properties
+- non-goals
+- viable options
+- operational and migration consequences
+- reversibility
+- unresolved unknowns
+
+Score each option from 1–5 for:
+
+- correctness
+- simplicity
+- operational burden
+- security
+- observability
+- migration risk
+- future compatibility
+- solo-operator maintainability
+
+Recommend one option. Explain why it wins, what it sacrifices, and what evidence could overturn the decision.
+
+Produce a proposed ADR, but make no code changes.

prompt-packs/quirk/prompts/quirk-build.prompt.md

@@ -0,0 +1,30 @@
+---
+name: quirk-build
+description: Implement a scoped feature with proof
+agent: agent
+argument-hint: feature, issue, or desired outcome
+---
+
+Implement the requested outcome in the smallest coherent change.
+
+Before editing:
+
+1. Inspect relevant repository instructions and nearby patterns.
+2. State the intended behavior and acceptance criteria.
+3. Identify affected contracts, schemas, APIs, tests, and documentation.
+4. Flag ambiguities that would materially alter the implementation.
+
+During implementation:
+
+- Preserve existing architecture unless evidence justifies changing it.
+- Reuse established patterns before introducing abstractions.
+- Keep domain logic separate from transport and presentation.
+- Validate external input at boundaries.
+- Add or update proportionate tests.
+- Do not silently expand scope.
+
+After implementation:
+
+- Run the relevant checks.
+- Report files changed, behavior added, evidence obtained, residual risks, and checks not run.
+- Do not claim success without verification.

prompt-packs/quirk/prompts/quirk-compound.prompt.md

@@ -0,0 +1,32 @@
+---
+name: quirk-compound
+description: Turn repository work into reusable Quirk capability
+agent: plan
+---
+
+Inspect the completed feature, fix, or workflow and determine what should compound.
+
+Look for:
+
+- reusable domain logic
+- stable interfaces
+- repeatable operating procedures
+- prompts or agent skills
+- fixtures and evaluation cases
+- templates or generators
+- observability patterns
+- newly proven architectural rules
+- documentation worth preserving
+- productizable capabilities
+
+Classify each candidate:
+
+- **LOCAL** — should remain repository-specific.
+- **SHARED** — belongs in a Quirk package, template, or convention.
+- **SKILL** — should become an agent-loadable workflow.
+- **CANON** — should become a Quirk Core rule or schema.
+- **OFFER** — could become a customer-facing capability.
+
+Recommend only extractions whose future reuse exceeds their maintenance cost.
+
+Return the single highest-value extraction, its evidence, destination, interface, and smallest implementation plan.

prompt-packs/quirk/prompts/quirk-core-contract.prompt.md

@@ -0,0 +1,35 @@
+---
+name: quirk-core-contract
+description: Design or inspect a Quirk Core contract
+agent: plan
+---
+
+Model this feature across the three Quirk Core layers:
+
+1. **Canonical** — Git-backed definitions, identity, rules, and schemas.
+2. **Runtime** — enforcement, permissions, validation, and execution.
+3. **Projection** — query-optimized database representations.
+
+Specify:
+
+- authoritative source for every field
+- legal writers
+- validation location
+- version and compatibility rules
+- write serialization
+- partial-write behavior
+- projection delay and reconciliation
+- audit events
+- override permissions
+- failure recovery
+- tests proving cross-layer consistency
+
+Reject designs that permit multiple undeclared sources of truth.
+
+Return:
+
+1. Contract table.
+2. State transitions.
+3. Failure matrix.
+4. Minimal schema and API changes.
+5. Open decisions requiring Bryan's authority.

prompt-packs/quirk/prompts/quirk-deps.prompt.md

@@ -0,0 +1,34 @@
+---
+name: quirk-deps
+description: Audit dependency changes and upgrade risk
+agent: ask
+---
+
+Analyze the dependency changes in the current branch or pull request.
+
+For every changed direct dependency determine:
+
+- previous and new versions
+- major, minor, patch, prerelease, or lockfile-only change
+- why it appears in the dependency graph
+- relevant breaking or behavioral changes
+- runtime, build, security, and peer-dependency risk
+- required code or configuration migrations
+- existing test coverage for affected behavior
+
+Inspect lockfile changes for:
+
+- unexpected transitive churn
+- duplicate package versions
+- runtime substitutions
+- removed integrity protections
+- changed install scripts
+- ecosystem or engine requirement changes
+
+Conclude with:
+
+- **SAFE TO APPROVE**
+- **APPROVE AFTER SPECIFIED CHECKS**
+- **REQUEST CHANGES**
+
+Draft a concise GitHub review comment supporting that verdict.

prompt-packs/quirk/prompts/quirk-fix-ci.prompt.md

@@ -0,0 +1,25 @@
+---
+name: quirk-fix-ci
+description: Diagnose and repair failing repository checks
+agent: agent
+---
+
+Diagnose the failing check from evidence.
+
+Process:
+
+1. Read the complete failure output.
+2. Identify the earliest meaningful error, not merely the final cascade.
+3. Reproduce it locally when possible.
+4. Determine whether the cause is code, tests, configuration, environment, dependency drift, or workflow logic.
+5. Implement the narrowest durable repair.
+6. Re-run the failed check and relevant neighboring checks.
+
+Do not:
+
+- weaken assertions to manufacture a pass
+- disable checks without explicit justification
+- conceal type or lint failures
+- perform unrelated cleanup
+
+Report root cause, repair, verification evidence, and anything still dependent on CI-only infrastructure.

prompt-packs/quirk/prompts/quirk-orient.prompt.md

@@ -0,0 +1,25 @@
+---
+name: quirk-orient
+description: Build an evidence-backed map of this repository
+agent: ask
+---
+
+Inspect this repository as a new Quirk Systems operator.
+
+Determine:
+
+1. What the system actually does.
+2. Its architecture, boundaries, and runtime data flow.
+3. The canonical commands for install, development, testing, linting, and build.
+4. Important entry points, schemas, APIs, jobs, and integrations.
+5. Where documentation disagrees with implementation.
+6. Fragile, unfinished, duplicated, or misleading areas.
+7. The five most valuable next actions.
+
+Separate findings into:
+
+- **VERIFIED** — directly supported by code or configuration.
+- **INFERRED** — strongly suggested but not proven.
+- **UNKNOWN** — requires human input or external access.
+
+Cite repository paths for every important claim. Make no changes.

prompt-packs/quirk/prompts/quirk-poke-holes.prompt.md

@@ -0,0 +1,37 @@
+---
+name: quirk-poke-holes
+description: Adversarially test a feature, plan, or architecture
+agent: plan
+---
+
+Assume the proposed design is attractive, plausible, and incomplete.
+
+Try to break it through:
+
+- invalid assumptions
+- conflicting sources of truth
+- stale or reordered events
+- authorization boundary mistakes
+- malformed or adversarial input
+- partial writes and retry storms
+- concurrency and duplicate execution
+- schema evolution
+- dependency or provider failure
+- observability gaps
+- operator confusion
+- unjustified abstractions
+
+Return a risk register:
+
+| Risk | Trigger | Consequence | Existing defense | Missing defense | Test |
+| --- | --- | --- | --- | --- | --- |
+
+Then identify:
+
+1. The fatal flaw, if one exists.
+2. The cheapest uncertainty-reducing experiment.
+3. What should be simplified.
+4. What must be decided before implementation.
+5. **GO**, **REVISE**, or **STOP** guidance.
+
+Do not modify code.

prompt-packs/quirk/prompts/quirk-review.prompt.md

@@ -0,0 +1,36 @@
+---
+name: quirk-review
+description: Perform a decision-grade code or pull-request review
+agent: ask
+---
+
+Review the selected changes against the repository's actual conventions.
+
+Prioritize:
+
+1. Incorrect behavior.
+2. Security, authorization, privacy, or secret-handling failures.
+3. Data loss and migration hazards.
+4. Broken public contracts or backward compatibility.
+5. Race conditions, retries, partial failure, and idempotency.
+6. Missing tests for meaningful behavior.
+7. Performance regressions.
+8. Unnecessary complexity.
+
+For every finding include:
+
+- Severity: blocker, high, medium, or low.
+- Exact location.
+- Failure scenario.
+- Why it matters.
+- Smallest credible correction.
+
+Do not report hypothetical style preferences as defects.
+
+Finish with exactly one verdict:
+
+- **APPROVE**
+- **APPROVE WITH NON-BLOCKING NOTES**
+- **REQUEST CHANGES**
+
+Explain what evidence would change the verdict.