promptkit/docs/development.md

Development

This is the contributor entry point for Promptkit, a reusable Go library. All contributors must read the architecture policy before making changes.

Initial Orientation

Before starting work:

1. inspect the working tree and preserve unrelated changes;
2. read the policy, contract, and internal documents listed for the task;
3. inspect the relevant implementation and tests before deciding how to change them; and
4. keep documentation limited to implemented behavior unless an accepted decision or temporary roadmap explicitly owns future work.

Start with:

• the architecture policy for library boundaries, dependency direction, invariants, and non-goals;
• the internal component overview for the current package and component inventory;
• the documentation policy before changing documentation;
• the testing policy before adding, rewriting, or deleting tests; and
• the release procedure for version and publication work.

Task-Specific Reading Guide

Task	Read before changing
Root public API	The architecture policy, consumer guide, testing policy, and existing GoDoc.
Prompt, profile, or schema formats	The framework format reference, owning parser or validator package, and documentation policy.
Source loading or validation	The framework format reference, internal source document, and owning package tests.
Model-client behavior	The OpenAI-compatible integration contract, internal model-client document, and owning package tests.
Internal package implementation	The architecture policy, internal component overview, and focused internal document listed for that package.
Tests or test fixtures	The testing policy, owning package, and focused internal document listed by the component overview.
Maintained example	The example, consumer guide, framework format reference, and documentation policy.
Documentation	The documentation policy and canonical owner of every affected contract.
Release preparation or publication	The release procedure.

For cross-cutting changes, follow every applicable row. Do not create placeholder documents for packages, APIs, or integrations that do not yet exist.

Maintainer Validation

This section is the canonical local validation workflow for Promptkit. Run every command from the repository root before accepting a change. The test suite and maintained examples are deterministic, offline, and require no real provider credentials.

Tests, Analysis, Build, And Examples

Run the ordinary and race-enabled suites, static analysis, the build, and both maintained consumer examples:

go test ./...
go test -race ./...
go vet ./...
go build ./...
go run ./examples/go-library/prepare
go run ./examples/go-library/run

Both examples must exit successfully. Review their JSON output: preparation must report the selected offline prompt, profile, model, and message count; execution must report the deterministic generated output, successful validation, selected offline model, and usage. Neither command may contact a provider or require credentials.

Go Formatting

Check every tracked Go file. The final command must succeed and the captured list must be empty:

unformatted=$(
    git ls-files '*.go' |
        while IFS= read -r go_file
        do
            gofmt -l "$go_file"
        done
)
test -z "$unformatted"

Local Markdown Links

Use the Python standard library to verify every repository-relative Markdown target and local heading fragment. The check is offline and prints nothing on success:

python3 - <<'PY'
from pathlib import Path
import re
import subprocess
import sys
from urllib.parse import unquote

root = Path.cwd().resolve()
markdown_files = [
    root / name
    for name in subprocess.check_output(
        ["git", "ls-files", "*.md"], text=True
    ).splitlines()
]
link_pattern = re.compile(r"!?\[[^]]*\]\(([^)]+)\)")
heading_pattern = re.compile(r"^#{1,6}\s+(.+?)\s*#*\s*$")
scheme_pattern = re.compile(r"^[a-z][a-z0-9+.-]*:", re.IGNORECASE)


def markdown_lines(path):
    in_fence = False
    fence = ""
    for line in path.read_text(encoding="utf-8").splitlines():
        stripped = line.lstrip()
        marker = stripped[:3]
        if marker in {"```", "~~~"}:
            if not in_fence:
                in_fence = True
                fence = marker
            elif marker == fence:
                in_fence = False
                fence = ""
            continue
        if not in_fence:
            yield line


anchor_cache = {}


def anchors(path):
    if path in anchor_cache:
        return anchor_cache[path]
    found = set()
    counts = {}
    for line in markdown_lines(path):
        match = heading_pattern.match(line)
        if not match:
            continue
        heading = re.sub(r"<[^>]+>", "", match.group(1)).replace("`", "")
        base = re.sub(r"[^\w\- ]", "", heading.lower()).replace(" ", "-")
        count = counts.get(base, 0)
        counts[base] = count + 1
        found.add(base if count == 0 else f"{base}-{count}")
    anchor_cache[path] = found
    return found


failures = []
for source in markdown_files:
    text = "\n".join(markdown_lines(source))
    for match in link_pattern.finditer(text):
        target = match.group(1).strip()
        if target.startswith("<") and target.endswith(">"):
            target = target[1:-1]
        if scheme_pattern.match(target) or target.startswith("//"):
            continue
        path_text, separator, fragment = target.partition("#")
        destination = source if not path_text else source.parent / unquote(path_text)
        try:
            destination = destination.resolve()
            destination.relative_to(root)
        except ValueError:
            failures.append(f"{source.relative_to(root)}: escapes repository: {target}")
            continue
        if not destination.exists():
            failures.append(f"{source.relative_to(root)}: missing target: {target}")
            continue
        if separator and destination.suffix.lower() == ".md":
            fragment = unquote(fragment).lower()
            if fragment not in anchors(destination):
                failures.append(f"{source.relative_to(root)}: missing anchor: {target}")

if failures:
    print("\n".join(failures), file=sys.stderr)
    raise SystemExit(1)
PY

Repository Hygiene And Review

Reject an active Go workspace, tracked workspace files, a vendor tree, or a module replacement:

case "$(go env GOWORK)" in
    ''|off) ;;
    *) printf '%s\n' 'an active Go workspace is not allowed' >&2; exit 1 ;;
esac
test -z "$(git ls-files go.work go.work.sum)"
test ! -e vendor
if grep -Eq '^[[:space:]]*replace([[:space:]]|\()' go.mod
then
    printf '%s\n' 'go.mod contains a replacement' >&2
    exit 1
fi

Check whitespace in both unstaged and staged changes. List ignored files and scan tracked content for common credential forms:

git diff --check
git diff --cached --check
test -z "$(git ls-files --others --ignored --exclude-standard)"
credential_pattern='-----BEGIN ([A-Z0-9]+ )?PRIV''ATE KEY-----|AKI''A[0-9A-Z]{16}|gh[pousr]_[A-Za-z0-9]{36,}|sk-[A-Za-z0-9]{32,}'
if git grep -nEI -e "$credential_pattern" -- .
then
    printf '%s\n' 'possible credential found' >&2
    exit 1
fi

Inspect git status --short --untracked-files=all and the complete diff before accepting a change. The status may contain only the intended source changes during development. Reject credentials, private keys, environment files, generated binaries, test or coverage output, downloaded assets, template residue, and any other artifact that does not belong in source control. The credential scan catches common forms but does not replace inspection of the actual change.

After committing the accepted change, require a clean candidate:

test -z "$(git status --porcelain)"