Skip to main content

Developer Workflow

The KeyNova Platform Registry is the single source of truth for what exists in the platform. Before you write or change code, check the registry first.

Before you code​

Ask in this order:

  1. Is this already tracked?

    # From hmp-docs/
    cd tools/registry
    # Search for your feature by keyword
    grep -ril "<keyword>" ../../registry/stories/

    If a story already exists, link your PR to its ID (e.g. ST-003-005).

  2. Which epic/story does this belong to? Browse at http://localhost:3000/docs/platform-registry (Docusaurus) or directly in registry/epics/ + registry/stories/.

  3. Does your change touch any registered entity? Consult the Drift Dashboard — are there open findings in the area you're modifying?

While you code​

  • When you add a new API route, UI page, event topic, Prisma model, or test file, update the corresponding registry YAML in the same commit.
  • When you flip a story from unshipped to shipped, update its YAML's status field (in-progress → built or verified).
  • If you delete / rename code, remove or update the corresponding entity YAML so the scanner doesn't generate drift findings.

Quick-and-dirty rule: if you added a file whose basename starts with @Controller, export default function (Next.js page), a Prisma model, or KafkaProducer.send with a new topic, the registry needs a new YAML.

Before you push​

cd hmp-docs
npx tsx tools/registry/src/cli.ts validate-yaml      # schema + YAML parse
npx tsx tools/registry/src/cli.ts check-cross-links  # references resolve
npx tsx tools/registry/src/cli.ts drift-check        # code ↔ registry drift

All three must pass locally. CI will enforce validate-yaml and check-cross-links as blocking gates (SP-6 gate promotion) — if they fail, your PR won't merge.

PR template​

When you open a PR on hmp-docs or any KeyNova repo that touches the registry, fill out the Registry impact section of the PR template (.azuredevops/pull_request_template.md). The Azure Pipeline will auto-post a drift summary comment on your PR.

Cycle cadence​

  • Daily: validate-yaml + check-cross-links on every PR
  • Weekly (first 6 weeks, SP-4 cycle): drift-check full report, reviewer-on-rotation triages top-20 findings
  • Post SP-4: drift-check weekly or biweekly, depending on finding volume
  • Quarterly: audit stale stories — any status: built story with no meaningful implementations.* growth for 90 days is a candidate for cleanup

Brainstorming new features​

When using AI assistants (Claude Code, subagents) to brainstorm a new feature, ask them to read the registry first:

Before proposing the implementation for <feature>, read registry/epics/EP-*.yaml to find the parent epic, then list any existing stories in that epic's module that might overlap. Don't suggest an approach that duplicates an already-tracked story.

This is the brainstorming-skill convention; formal hook integration (into ~/.claude/skills/brainstorming/) is out of scope for SP-5 — it's a per-developer setup documented in the superpowers skills.