Karvey

Karvey — Method Orchestrator

Karvey is an ona/selknam word meaning Afán ('Afán' = zeal/drive). A stack-agnostic business development method (web, mobile/iOS/Android, desktop, CLI, API, embedded…). Created by Mauricio Quezada Ibáñez (HainTech). See "Authorship, license, and trademark" at the end.

Purpose

The entry point to the Karvey Method. It shows the complete pipeline, the current state of a specific change, and guides the engineer toward the next skill to run. It works for any stack: the project declares its targets and each phase adapts (see rules/targets.md).

The Karvey Method

Karvey is a spec-driven development (SDD) method for enterprise projects, stack-agnostic. It combines:

• Pre-spec interrogation (grill-me style) + "10-star product" reframe: discover and improve what's going to be built before specifying it
• PRD as foundation: every change is born from a Product Requirements Document (prd.md); the EARS requirements trace back to it
• EARS requirements + living specs (openspec/kiro style): formal, cumulative specifications
• Navigable mockup (with shotgun mode for variants): validate UX before designing
• Systemic graphic design with 0-10 scoring: OKLCH colors, typography, spacing, per platform (WCAG/HIG/Material)
• Enterprise architecture: layered security Tiers 1–4, diagrams, edge cases, trust boundaries, cloud infrastructure
• Infrastructure as code + CI/CD: IaC and pipelines per cloud and git platform, with a security review
• 10–30 min AI tasks + ClickUp or Markdown management
• DB/Backend/Frontend + E2E testing in the target's real runtime, with benchmark and regression
• 8-dimension QA: includes a blocking security gate (OWASP+STRIDE), cross-model second opinion, and visual audit
• Orderly deployment: feature branch → dev → PR to master, triggered by the pipeline, with post-deploy canary
• Semver versioning + CHANGELOG per component/repo, with human + AI model traceability
• Persistent goal: a north star that every phase re-reads so it never stops until the result is achieved, while respecting the gates
• Spiral, not a line — iteration loop: testing/QA/real-runtime surface defects and new ideas; the iteration engine (karvey-iterate) routes each finding back to its edge (bug → incident tracker + QA micro-loop · spec-gap → re-open requirements · emergent → discovery backlog) so nothing is dropped. See rules/iteration-loop.md.
• Incident tracker (BUG-NN with state history) + discovery backlog (Markdown + ClickUp) so bugs and post-cycle ideas stay traceable (rules/incident-tracking.md, rules/backlog.md)
• Phase-close ritual: every phase/task closes with a mandatory management update (ClickUp comment + status + cascade) so tasks never go stale — see rules/phase-close.md
• Cross-cutting layer of support skills (investigate, second-opinion, health, browse, etc.) callable at any time
• Optional enforcement via hooks (git-flow + plan-gate) and archive with spec merge

Complete pipeline

PHASE 0 ─── /karvey-grill          → Pre-spec + 10-star reframe (+ platform/cloud)
PHASE 1 ─── /karvey-init           → change-id, project.json, prd.md, spec.json, ClickUp Epic
PHASE 2 ─── /karvey-requirements   → EARS requirements (trace to the PRD), spec-delta, approval
PHASE 3 ─── /karvey-mockup         → Navigable 3–4 levels + spec↔mockup validation (+ shotgun mode)
PHASE 4 ─── /karvey-design-graphic → OKLCH visual system + 0-10 scoring + visual components catalog
PHASE 5 ─── /karvey-architecture   → Architecture, Tiers, diagrams, edge cases, Cloud Infra
PHASE 6 ─── /karvey-infra          → IaC + CI/CD pipelines + infra security review
PHASE 7 ─── /karvey-tasks          → 10–30 min tasks, E{n}.F{n}.T{n}, ClickUp sprint
PHASE 8 ─── /karvey-impl           → Implementation DB→Backend→Frontend, commits + CHANGELOG
PHASE 9 ─── /karvey-test           → Unit + E2E in the target's real runtime, benchmark, regression
PHASE 10 ── /karvey-qa             → QA 8D + blocking security gate, REVISION_PR
PHASE 11 ── /karvey-deploy         → Orderly deployment feature→dev→PR master + canary
PHASE 12 ── /karvey-archive        → Merge spec-deltas, retro, docs, close Epic + backlog sweep

Feedback edges — the spiral (not part of the linear count)

Findings from test/qa/browse land in findings.md and are routed by /karvey-iterate:

   test · qa · browse ──→ findings.md ──→ /karvey-iterate (the engine)
                                              ├─ bug      → BUG-NN tracker → impl→test→qa micro-loop
                                              ├─ spec-gap → re-open PHASE 2 requirements (ripple only affected phases)
                                              └─ emergent → discovery backlog → future change-id (swept at archive)

A change is done only when findings.md has no open bug/spec-gap and all emergent are captured (convergence rule, rules/iteration-loop.md).

Cross-cutting layer — support skills (callable at any time)

These are not phases; they do not advance spec.json:phase forward. See rules/support-skills.md.

/karvey-iterate            → Iteration engine: route findings (bug/spec-gap/emergent) to their edge
/karvey-investigate        → Root-cause debugging (Iron Law: no fix without investigating)
/karvey-second-opinion     → Adversarial cross-model review (Claude vs another model)
/karvey-health             → 0-10 dashboard (type/lint/tests/dead-code) + trend
/karvey-browse             → "Give it eyes": the target's real runtime (browser/sim/CLI)
/karvey-checkpoint         → Save/restore work state (handoff)
/karvey-diagram            → Text → mermaid + excalidraw + SVG/PNG
/karvey-docs               → Diataxis + update stale docs + PDF
/karvey-guard              → Install/remove enforcement hooks; edit-lock
/karvey-devex              → Onboarding/DX review (time-to-hello-world)
/karvey-retro              → Retrospective (velocity, test health, per person)
/karvey-scrape             → Extract web data + encode it as a skill
/karvey-benchmark-models   → Compare models (latency/tokens/cost/quality)
/karvey-import             → Convert Kiro/gstack specs into Karvey (docs/spec/)
/karvey-standards          → Uplift engineering standards (golden paths) from the real system → standards repo

Support view: /karvey-context [--capability X] [--change Y] → dashboard + deployment queue.

Execution by argument

No arguments — Show the pipeline and project context

Show the pipeline above, then run the steps of /karvey-context (capabilities, active changes, archived ones, sprint, deployment queue).

With <change-id> — Show the change's current phase

cat docs/spec/changes/{change-id}/spec.json 2>/dev/null || echo "Not found"

Read spec.json and determine the current phase based on phase and approvals:

Convergence gate: before advancing from test/qa to deploy, findings.md must have no open bug/spec-gap and all emergent must be captured in the backlog (rules/iteration-loop.md). If not, the next step is /karvey-iterate, not forward.

Show the user the status (capability, phase, Tier, management, goal, approvals including infra, qa, deploy, plus iteration_count and open findings/backlog counts) and the next step.

With --phase <fase> — Detailed description of a phase

Valid phases: grill, init, requirements, mockup, design-graphic, architecture, infra, tasks, impl, test, qa, deploy, archive.

With --autoplan — Planning chain

Run the planning phases (0→5) in sequence, chaining approvals, escalating to the user only the substantive decisions (taste, scope, security). Inspired by gstack's autoplan. It does not skip the approval gates; it groups them.

Description of each phase

PHASE 0: /karvey-grill

Pre-spec interrogation + "10-star product" reframe (optional). Produces a synthesis (input to the PRD). Asks about git platform, cloud, IaC.

PHASE 1: /karvey-init

Creates/reads docs/spec/project.json (git, cloud, IaC, knowledge_sync, targets, repos, spec_repo, branch_flow, enforcement). Captures the goal. Generates change-id, prd.md, spec.json. ClickUp Epic or PLAN.md. Rules: project-config.md, clickup-protocol.md, living-specs.md, knowledge-sync.md, enforcement.md

PHASE 2: /karvey-requirements

EARS requirements, each one traced to a section of the PRD. requirements.md, spec-delta.md. Rules: ears-format.md, living-specs.md, security-tiers.md

PHASE 3: /karvey-mockup

Navigable 3–4 levels (deeper when the flow warrants it), adapted to the target. Shotgun mode (N variants + board). Includes a spec↔mockup validation pass: walk the mockup against requirements.md to catch spec-gaps before design/architecture/impl (cheap correction). mockup.html (or the target's equivalent).

PHASE 4: /karvey-design-graphic

OKLCH system + 0-10 scoring per dimension (what a 10 would be). Per-platform guidance (WCAG/HIG/Material). Derives a visual components catalog (art brief per screen/modal/component: states + background art, light+dark, safe zones) exhaustively from the mockup. design-spec.md, design-components.md.

PHASE 5: /karvey-architecture

Boundaries, security per Tier, diagrams (mermaid), edge cases, trust boundaries, test coverage plan, Cloud Infrastructure section. architecture.md. Rules: security-tiers.md

PHASE 6: /karvey-infra

IaC (Terraform/Bicep/Pulumi) + CI/CD pipelines (GitHub Actions/Azure Pipelines), idempotent + platform auto-detection + infra security review. infra.md. Rules: project-config.md, deploy-workflow.md, security-tiers.md, changelog-policy.md

PHASE 7: /karvey-tasks

10–30 min tasks, E{n}.F{n}.T{n} [DB/Backend/Frontend/Infra]. Reads architecture.md + infra.md. tasks.md. Rules: clickup-protocol.md

PHASE 8: /karvey-impl

Executes tasks on feature/{change-id} (never dev/master). Version bump + CHANGELOG per commit (human + AI model + why). Rules: deploy-workflow.md, changelog-policy.md, versioning.md

PHASE 9: /karvey-test

Unit + E2E in the target's real runtime, performance benchmark, regression tests. Writes observations to findings.md (classified bug/spec-gap/emergent) and promotes confirmed bugs to the BUG-NN incident tracker. test_evidence.md. Rules: targets.md, iteration-loop.md, incident-tracking.md, phase-close.md

PHASE 10: /karvey-qa

8-dimension QA: Security (blocking gate, OWASP+STRIDE), Errors, Consistency, Impact, Env vars, Versioning (CHANGELOG), cross-model Second-opinion, Visual audit. Appends findings to findings.md; on open bug/spec-gap it routes via /karvey-iterate instead of advancing. REVISION_PR_{n}_{date}.md. Rules: changelog-policy.md, versioning.md, iteration-loop.md, phase-close.md

PHASE 11: /karvey-deploy

Orderly per-repo flow: pull → feature → pull → merge dev (DEV pipeline) → canary → pull → PR dev→master (PROD with human OK) → canary. Semver bump + CHANGELOG per component/repo. Version visible in the front end (recommended). Never deploy manually. Rules: deploy-workflow.md, versioning.md, changelog-policy.md, project-config.md

PHASE 12: /karvey-archive

Merge spec-deltas into living specs, archive, close the Epic. Backlog sweep: review open emergent items from this change and offer to promote them into new change-ids (so post-cycle discoveries don't evaporate). Recommended optional: /karvey-retro + /karvey-docs. Rules: living-specs.md, backlog.md, phase-close.md

Method directory structure

docs/spec/ lives in the project's main repo (spec_repo). A project has 1 or more repos, never zero.

docs/spec/
├── project.json                       ← Config (git, cloud, IaC, targets, knowledge_sync, repos, enforcement)
├── backlog.md                         ← Discovery backlog (emergent items → future change-ids)
├── incidents-index.md                 ← Global index of all BUG-NN across repos + current state
├── standards/                         ← Engineering golden paths ("how we build here", per layer)
│   ├── _index.md  · db.md · backend.md · frontend.md   ← loaded as a hard constraint by architecture/impl
├── specs/{capability}/spec.md         ← Living specs (cumulative per capability)
└── changes/{change-id}/
    ├── spec.json                      ← Metadata, phase, approvals, goal, iteration_count, revision_history
    ├── prd.md                         ← Product Requirements Document
    ├── requirements.md                ← EARS (trace to the PRD)
    ├── spec-delta.md  · mockup.* · design-spec.md
    ├── architecture.md                ← + Cloud Infrastructure
    ├── infra.md  · tasks.md  · checkpoint.md
    ├── findings.md                    ← Triage inbox (bug/spec-gap/emergent) routed by karvey-iterate
    ├── deviations.md                  ← Approved departures from engineering standards (design mode)
    ├── PLAN.md (if markdown)  · IMPLEMENTED
    └── archive/{YYYY-MM-DD}-{change-id}/

The code (incl. IaC and pipelines), each repo's docs/bugs_dev_testing.md incident tracker, the per-component/repo CHANGELOG.md, and the settings.json hooks live in each repo of project.json:repos.

Shared rules

If you come from Kiro or gstack — equivalences

Karvey absorbs the value of both. What in gstack are standalone commands lives here in a phase or in the cross-cutting layer.

N/A (gstack-proprietary, with a generic equivalent): open-gstack-browser → karvey-browse runtime; gstack-upgrade → N/A; pair-agent/gbrain → knowledge-sync.

Quick reference commands

/karvey [<change-id>] [--phase <f>] [--autoplan]   → State / pipeline / chained planning
/karvey-context                                     → Dashboard + deployment queue
Phases: grill init requirements mockup design-graphic architecture infra
        tasks impl test qa deploy archive
Support: iterate investigate second-opinion health browse checkpoint diagram
        docs guard devex retro scrape benchmark-models import standards

Authorship, license, and trademark

• Etymology: Karvey is an ona/selknam word meaning Afán ('Afán' = zeal/drive).
• Author: A business development model created by Mauricio Quezada Ibáñez, HainTech. Owned by HainTech.
• License: Apache License 2.0 — see LICENSE and NOTICE. Anyone may use, modify, and adapt it (incl. commercial use) while respecting the license.
• Trademark: "Karvey" and the karvey-* convention are a trademark of HainTech. Adaptations permitted with attribution; see TRADEMARK.md.
• Credits / inspiration: Karvey synthesizes the first-hand experience of Mauricio Quezada Ibáñez (HainTech) with conceptual ideas from Kiro (spec-driven / cc-sdd) and gstack (Garry Tan). It is synthesis and conceptual inspiration; it does not incorporate code from those projects.

Part of the Karvey™ Method — © HainTech, by Mauricio Quezada Ibáñez · Apache 2.0 · see karvey/LICENSE and karvey/TRADEMARK.md. Karvey = Afán, an ona/selknam word.