/init

name: init
description: Bootstrap project context (project.intent.md and project.glossary.json) from an existing codebase using deterministic scan + LLM synthesis + interactive editing. Use --harness to scaffold additional repo-level harness docs.
arguments:
  - name: flags
    description: "Optional: --force to overwrite existing files, --harness to scaffold repo-level harness docs, --project-root <path> to specify target directory"
    required: false

Signum Init: Project Context Bootstrapping

You are the Signum Init orchestrator. Bootstrap project context for a new or existing project.

The user's arguments: `$ARGUMENTS`

Pipeline

SCAN → SYNTHESIZE → PRESENT → VERIFY

---

Step 0: Parse Arguments

Parse `$ARGUMENTS`:

• If `--force` is present, set FORCE_MODE=true (overwrite existing files without prompting)
• If `--harness` is present, set HARNESS_MODE=true (scaffold repo-level harness docs)
• If `--project-root <path>` is present, use that path. Otherwise use current directory.
• Any other argument: print usage and stop.

**Usage:**

/signum:init [--force] [--harness] [--project-root <path>]

For Claude Code plugin usage, `/signum:init` is the canonical form. `--harness` requires Signum `>= v4.18.0`.

---

Step 1: SCAN (deterministic)

1a. Resolve Signum helper paths

Run:

resolve_signum_helper() {
  local helper="$1"
  if [ -n "${CLAUDE_PLUGIN_ROOT:-}" ] && [ -f "${CLAUDE_PLUGIN_ROOT}/lib/${helper}" ]; then
    printf '%s\n' "${CLAUDE_PLUGIN_ROOT}/lib/${helper}"
    return 0
  fi
  if [ -f "lib/${helper}" ]; then
    printf '%s\n' "lib/${helper}"
    return 0
  fi
  echo "ERROR: Signum helper not found: ${helper}" >&2
  return 1
}

INIT_SCANNER_PATH=$(resolve_signum_helper "init-scanner.sh") || exit 1
INIT_HARNESS_SCAFFOLD_PATH=$(resolve_signum_helper "init-harness-scaffold.sh") || exit 1
printf 'INIT_SCANNER_PATH=%s\n' "$INIT_SCANNER_PATH"
printf 'INIT_HARNESS_SCAFFOLD_PATH=%s\n' "$INIT_HARNESS_SCAFFOLD_PATH"

Save the resolved helper paths as `INIT_SCANNER_PATH` and `INIT_HARNESS_SCAFFOLD_PATH`.

1b. Check for existing files

Run:

ls project.intent.md 2>/dev/null && echo "INTENT_EXISTS=true" || echo "INTENT_EXISTS=false"
ls project.glossary.json 2>/dev/null && echo "GLOSSARY_EXISTS=true" || echo "GLOSSARY_EXISTS=false"

If `HARNESS_MODE=true`, also run:

bash "$INIT_HARNESS_SCAFFOLD_PATH" --project-root "${PROJECT_ROOT:-.}" 2>/dev/null

Save this JSON as HARNESS_SCAFFOLD. It contains the additional harness-doc drafts plus `.missingCount` / `.existingCount`.

If `HARNESS_MODE=true` AND **both** `project.intent.md` and `project.glossary.json` already exist AND `--force` was NOT provided:

• Preserve the existing context files (do NOT regenerate them)
• Scaffold only the harness docs whose `exists=false`
• If `HARNESS_SCAFFOLD.missingCount == 0`, print:

  Harness docs already exist. No files written.

and stop.

If `HARNESS_MODE=false` AND (`project.intent.md` OR `project.glossary.json` already exists) AND `--force` was NOT provided:

• Print this message and STOP:

  project.intent.md already exists.

  To overwrite, run: /signum:init --force
  To update (merge), run: /signum:init --force

1c. Run scanner

bash "$INIT_SCANNER_PATH" --project-root "${PROJECT_ROOT:-.}" 2>/dev/null

Save the output JSON as SCAN_SIGNALS. This contains all signals needed for synthesis.

Report to user:

SCAN complete. Found signals:
  - Authoritative docs: [yes/no]
  - CLAUDE.md: [yes/no]
  - README.md: [yes/no]
  - Package manifest: [yes/no]
  - Git history (6 months): [N commits]
  - Public entrypoints: [N found]
  - Existing glossary: [yes/no]
  - Existing intent: [yes/no]
  - Harness docs missing: [N]   (only when --harness)
  - Harness docs already present: [N]   (only when --harness)

---

Step 2: SYNTHESIZE (LLM)

If `HARNESS_MODE=true`, harness docs come from `INIT_HARNESS_SCAFFOLD_PATH` (deterministic; do NOT ask the synthesizer to invent them).

If existing `project.intent.md` **and** `project.glossary.json` are both being preserved (harness-only brownfield mode), skip the synthesizer entirely.

Otherwise, pass SCAN_SIGNALS to the init-synthesizer agent. The synthesizer will: 1. Apply source precedence hierarchy (docs/ > CLAUDE.md > README > package.json) 2. Generate `project.intent.md` with evidence comments and confidence annotations 3. Generate `project.glossary.json` with canonicalTerms and aliases 4. Emit coverage summary

**Key rules enforced by synthesizer:**

• Non-Goals ONLY from explicit negative signals (ADRs rejected, README "Not supported", CLAUDE.md exclusions)
• Every section annotated with `<!-- evidence: ... -->` and `<!-- confidence: high|medium|low -->`
• Low confidence → TODO markers, not fabricated content
• Existing glossary terms preserved (merge-only)

---

Step 3: PRESENT (interactive)

Default mode (no `--harness`)

Show the generated drafts to the user with a separator:

════════════════════════════════════════
DRAFT: project.intent.md
════════════════════════════════════════
[full generated content]

════════════════════════════════════════
DRAFT: project.glossary.json
════════════════════════════════════════
[full generated content]

════════════════════════════════════════

Then ask:

Review the drafts above.

Options:
  [1] Accept and write both files
  [2] Edit intent first, then write
  [3] Edit glossary first, then write
  [4] Accept intent only, skip glossary
  [5] Cancel (write nothing)

Enter choice (1-5):

Wait for user confirmation before writing any file.

If the user chooses to edit (options 2 or 3), open the draft for editing and present the revised version before final write.

On cancel (option 5): print "Cancelled. No files written." and stop.

Harness mode (`--harness`)

If brownfield preserve mode is active (existing intent + glossary kept as-is), show only the missing harness-doc drafts:

═════