Karvey Init

Karvey Init

Purpose

Initialize the structure of a new specification and register the Epic in the management system (ClickUp or Markdown).

Execution steps

Step 1 — Verify pre-spec context

If a karvey-grill summary exists in the conversation, use it to pre-populate the fields. If not, ask the user: "Briefly describe the problem this change solves."

Step 2 — Generate change-id

If $ARGUMENTS includes the change-id, use it. If not, generate it from the description:

• Format: {add|fix|update|remove}-{descriptive-url-safe-name}
• Examples: add-call-transfer, fix-webhook-retry, update-tenant-config
• Verify it doesn't already exist in docs/spec/changes/: find docs/spec/changes -maxdepth 1 -type d -name "{change-id}"
• If there's a conflict, add a numeric suffix: add-call-transfer-2

Step 3 — Project config (project.json)

Check whether docs/spec/project.json exists.

If it ALREADY exists: read it and reuse its values. Don't ask anything about this config again.

If it does NOT exist: create it. Pre-populate from the karvey-grill synthesis if it's available in the conversation; ask for or infer the missing fields. The complete schema is in karvey/rules/project-config.md (cite that rule). Fields:

• git_platform: github | azure_devops.
• cloud.provider: azure | gcp | aws | mixed | none.
• iac_tool: terraform | bicep | pulumi | none.
• knowledge_sync: decide based on karvey/rules/knowledge-sync.md — if an Obsidian MCP is available in the session → "obsidian"; if not → "graphify".
• repos: array of the project's repos. MINIMUM 1 element, never empty.
• spec_repo: if repos has 1 → that same one; if there are several → ask which is the main repo where docs/spec/ lives.
• branch_flow: by default { "feature_prefix": "feature/", "integration": "dev", "production": "master" }.

Write docs/spec/project.json with these values (see the schema in karvey/rules/project-config.md).

Step 3.5 — Enforcement opt-in (hooks)

After creating project.json, ask the user whether they want to enable the Karvey method's enforcement hooks. See the detail in karvey/rules/enforcement.md.

Do you want to enable Karvey's enforcement hooks? (OPT-IN, you can enable them later)
  - git-flow hook: blocks direct commits to the integration/production branches and enforces the feature-branch flow (reads branch_flow).
  - plan-gate hook: blocks modifications without an approved plan.

If they accept one or both: set the enforcement block in project.json:

"enforcement": {
  "git_flow_hook": true,
  "plan_gate_hook": true
}

(set true only on the ones the user accepted). Tell the user the hooks are installed by running:

/karvey-guard --install

karvey-guard --install writes the hooks into the project's settings.json, reading branch_flow from project.json.

If they do NOT accept: leave both flags at false. Enforcement is OPT-IN — never force it.

"enforcement": {
  "git_flow_hook": false,
  "plan_gate_hook": false
}

Step 4 — Ask about the management system

Does this project use ClickUp for management?

If YES (ClickUp):

• Ask: Which project/backlog does it belong to? (get the ClickUp backlog_list_id)
• Read the rule: rules/clickup-protocol.md

If NO (Markdown):

• A PLAN.md will be created in the change's directory
• No additional configuration is required

Step 5 — Collect metadata

Ask (or infer from the pre-spec context):

1. Capability: the functional domain it belongs to (e.g., call-management, authentication, notifications). If it doesn't exist in docs/spec/specs/, it will be created.
2. Security Tier: 1-4. Read rules/security-tiers.md to guide the user.
3. Layers involved: DB / Backend / Frontend / Infra (can be multiple)
4. Brief description: 1-2 lines of the problem it solves
5. Goal (the change's north star): the concrete objective being pursued — what observable, verifiable result defines the success of this change. Ask: "What is this change's north star? What concrete result do we want to achieve?". Save it verbatim in spec.json (goal) and reflect it as a highlighted section in prd.md.

Note — the goal provides persistence. The goal remains the change's north star across all phases: each Karvey phase re-reads it on start to pursue the result without stopping until it's achieved, always respecting the plan and security gates.

Step 6 — Create the directory structure

mkdir -p docs/spec/changes/{change-id}/specs/{capability}
mkdir -p docs/spec/specs/{capability}  # if it doesn't exist

If docs/spec/specs/{capability}/spec.md doesn't exist, create it:

# Spec: {Capability}

<!-- Living spec for the {capability} capability. Updated when each change is archived. -->

Step 7 — Create spec.json

Write docs/spec/changes/{change-id}/spec.json with:

{
  "change_id": "{change-id}",
  "capability": "{capability}",
  "description": "{brief description}",
  "goal": "{the change's north star: concrete, verifiable result that defines success}",
  "layers": ["{DB|Backend|Frontend|Infra}"],
  "created_at": "{ISO timestamp}",
  "updated_at": "{ISO timestamp}",
  "language": "es",
  "management": "{clickup|markdown}",
  "security_tier": {1-4},
  "phase": "init",
  "clickup": {
    "epic_id": "",
    "feature_ids": [],
    "backlog_list_id": "{list_id or empty}",
    "client_tag": "{tag or empty}"
  },
  "approvals": {
    "requirements": { "generated": false, "approved": false },
    "mockup": { "generated": false, "approved": false },
    "design_graphic": { "generated": false, "approved": false },
    "architecture": { "generated": false, "approved": false },
    "tasks": { "generated": false, "approved": false },
    "infra": { "generated": false, "approved": false },
    "qa": { "generated": false, "approved": false },
    "deploy": { "generated": false, "approved": false }
  }
}

Step 8 — Create prd.md

Write docs/spec/changes/{change-id}/prd.md (formal Product Requirements Document):

# PRD: {change-id}

## Executive summary
{2-3 line synthesis: what's being built and what for}

## 🎯 Goal (the change's north star)
> {concrete, verifiable result that defines the success of this change}

This goal is the north star that all Karvey phases pursue: each phase re-reads it on start to advance toward the result without stopping until it's achieved, respecting the plan and security gates.

## Problem and context
- **Who has it:** {affected users/roles}
- **Current situation:** {how it's solved today or why it hurts}
- **Impact:** {cost of not solving it}

## Objectives and success metrics
{measurable objectives, e.g. "reduce X from N to M", "enable Y for Z users"}

## User stories / main use cases
- As a {role}, I want {action} so that {benefit}.
- {…}

## Scope (in scope)
- {what IS part of this change}

## Out of scope
- {what is NOT included and why}

## Stakeholders
{who requests, who approves, who is impacted}

## Constraints
- Security Tier: {N} — {justification}
- Prerequisite dependencies: {list}

## Acceptance criteria
{verifiable conditions to consider the change complete}

Step 9A — Create the Epic in ClickUp (if management=clickup)

Read credentials from .connections.json (see rules/clickup-protocol.md). If it doesn't exist, create it and add it to .gitignore before continuing. Determine the next Epic number by searching in ClickUp:

clickup_search
  keywords: "E{1..99}"
  filters.location.categories: ["{backlog_list_id}"]

Create the Epic:

clickup_create_task
  name: "E{n} {Epic name}"
  list_id: "{backlog_list_id}"
  task_type: "Epic"
  description: (see format in the rules)
  tags: ["{client_tag}"]

Update spec.json with clickup.epic_id.

Epic description format:

E{n}: {Epic name}

Definition:
{2-3 paragraph description: what problem it solves, for whom, why it matters}

Strategic Value:
{business impact}

Security Tier: {N} — {justification}

Design Decisions:
(pending — completed in karvey-architecture)

Features:
(pending — completed in karvey-requirements)

Built with the Karvey Method

Step 9B — Create PLAN.md (if management=markdown)

Write docs/spec/changes/{change-id}/PLAN.md:

# Plan: {change-id}

**Capability:** {capability} | **Security Tier:** {N} | **Layers:** {list}
**Created:** {date} | **Status:** 🟡 In progress

---

## Epic: {Name}

### Description
{problem, who, impact}

### Strategic value
{business impact}

### Design decisions
| Topic | Decision |
|------|----------|
| (pending — karvey-architecture) | |

---

## Features
(pending — karvey-requirements)

---

## Tasks
(pending — karvey-tasks)

---

## Task status
| Task | Status | Estimated time | Actual time |
|------|--------|----------------|-------------|
| (pending) | | | |

---

## History
| Date | Phase | Action |
|-------|------|--------|
| {date} | init | Spec initialized |

Step 9C — Update the knowledge graph

Sync knowledge per karvey/rules/knowledge-sync.md (Obsidian if available; at minimum /graphify docs/spec/ --update) to reflect the documents created. If docs/spec/graphify-out/ doesn't exist (first time in the project), invoke /graphify docs/spec/ without --update.

Step 10 — Final output

✅ Spec initialized: docs/spec/changes/{change-id}/

Project config: docs/spec/project.json (created | read)

Files created:
  - docs/spec/changes/{change-id}/spec.json
  - docs/spec/changes/{change-id}/prd.md
  - docs/spec/changes/{change-id}/PLAN.md (if markdown)
  - docs/spec/specs/{capability}/spec.md (if new capability)

Management: {ClickUp Epic E{n} created | PLAN.md created}
Security Tier: {N}

Next step:
/karvey-requirements {change-id}

Safety

• If docs/spec/changes/{change-id} already exists with a spec.json, ask before overwriting
• If ClickUp fails, offer to continue in markdown mode as a fallback
• Validate that the change-id is URL-safe (only lowercase letters, numbers, and hyphens)

Advance to the next phase

When you finish this phase and have the corresponding approval, actively ask the user: "Shall we advance to the Requirements phase now?"

• If they confirm → run /karvey-requirements {change-id}.
• If they prefer to review or adjust first → wait. Advancing is always with the user's OK (a gate of the method).
• If you resume in another session, /karvey {change-id} indicates which phase you're on and which one comes next.

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.