tp-spec

/tp-spec

Manage living spec deltas for a design: scaffold, validate, and merge spec-delta.md files into their domain base spec.

Argument: <design-name> (required) — must match an existing directory under three-pillars-docs/tp-designs/. Design names use only [a-z0-9-] characters; reject anything else before proceeding (see skills/_shared/validate-name.md).

Steps

1. Run first-run preflight per skills/_shared/first-run.md.

2. Dispatch to the subcommand — see §Subcommands below.

Subcommands

add <design>

Scaffold a spec-delta.md in the design directory from the template.

Refuse-to-clobber: if spec-delta.md already exists it is left untouched and the command exits 0 with a notice. In --auto mode this is a silent no-op.

/tp-spec add <design-name>

Creates: three-pillars-docs/tp-designs/<design>/spec-delta.md Template: skills/tp-spec/templates/spec-delta.template.md

validate <design>

Validate the design's spec-delta.md structurally, then run the drift scan over the matching domain spec tree.

/tp-spec validate <design-name> [--domain <domain>]

Validator API (exact signature):

import sys
sys.path.insert(0, "$TP_ROOT/skills/_shared")  # $TP_ROOT resolved per skills/_shared/first-run.md
from validate_artifact import validate_artifact
from pathlib import Path

verdict = validate_artifact("spec", Path(delta_path))   # type-first, Path arg

On BLOCKED: JSON verdict is printed to stderr and the command exits 1. On PASS: runs spec_drift.py scan over three-pillars-docs/specs/ and exits with its exit code (0 clean / 1 DRIFT).

The nonexistent .validate(text, type) signature is never used.

merge <design>

Merge the design's spec-delta.md into the domain base spec via the engine.

/tp-spec merge <design-name> [--domain <domain>]

Engine call (exact signature):

from spec_delta import merge, MergeConflict, SpecParseError

merged_text = merge(base_text, [delta_text])   # base_text: str, list of delta str