ground

Harness Ground — Technical Grounding to Spec

Transform a brief or idea into a specification that is reality-checked against the actual codebase — data models, API patterns, jobs, and UI components. The "Codebase Reality Check" section is the differentiator.

Prerequisites

Check for .harness/kb/stack-profile.md. If missing, tell the user to run /harness:init first.

Context Loading

Load ALL KB files from .harness/kb/ for comprehensive grounding:

• stack-profile.md — framework conventions, project structure

• data-layer.md — tables, relationships, constraints

• api-surface.md — endpoint patterns, middleware, auth

• async-jobs.md — background jobs, triggers, schedules

• ui-patterns.md — component patterns, state management

• integrations.md — external services, SDKs

Also search the live codebase — KB files are summaries, not exhaustive. For specific questions, grep/read the actual source files.

Process

Step 1: Find the Input

1. Brief path provided → Read from documents/shapings/ or target_dir
2. Recent brief exists → Scan for matching brief files
3. Fresh description → User describes the feature directly

If a brief exists, read it and confirm: "Grounding the brief from [date] about [topic]. Correct?"

Step 2: Deep-Query KB + Codebase

For each aspect of the feature, systematically check:

Question	Where to Look
What data entities exist?	data-layer.md + actual schema/model files
What columns/relationships?	ORM models, migration files, schema definitions
What jobs/async processes relate?	async-jobs.md + job definition files
What API endpoints exist?	api-surface.md + route/controller files
What middleware/auth pattern?	api-surface.md + middleware source files
What UI components exist?	ui-patterns.md + actual component directories
What integrations are relevant?	integrations.md + SDK/client source files

Step 3: Produce Grounded Spec

Structure:

1. Summary — One paragraph: what this builds and why

2. Codebase Reality Check

   • What exists and can be reused (with file paths)

   • What conflicts with existing patterns

   • What's completely new

3. Data Model Changes

   • New tables/collections/models

   • Column additions to existing tables

   • New relationships, indexes, constraints

   • Migration plan

4. API Changes

   • New endpoints following existing conventions

   • Modified handlers

   • Auth requirements

5. UI Changes

   • New components/pages

   • Modified existing components

   • Which existing patterns to follow

6. Async/Job Changes

   • New jobs or triggers

   • Modified schedules

   • Event handling changes

7. Integration Changes

   • New external service connections

   • Modified existing integrations

8. Implementation Order

   • Ordered phases with dependencies

   • What can be parallelized

9. Test Scenarios

   • Happy paths

   • Edge cases

   • Error paths

Step 4: Save

Save to {target_dir}/spec-{slug}-{date}.md with frontmatter:

---
title: "{spec title}"
type: spec
date: {ISO date}
tags: [{relevant}, {tags}]
source-brief: "{brief filename if applicable}"
next-skill: design
---

Also store via MCP: call harness_add_skillflow_step with skill_type: "ground".

Guardrails

• Every claim about "what exists" must include a file path

• Never propose a pattern that conflicts with existing conventions without flagging the conflict

• If the spec requires changes to shared code, call it out explicitly with impact analysis

• Migration plans should be safe — backward compatible where possible