Forge Reference

Forge is the goatcs-harness subsystem that authors skills from text briefs. Given a natural-language description of a desired skill, forge emits a complete native skill package.

What forge emits

A forge run produces:

text 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
my-skill/
  graph.json              # Topology: nodes, edges, metadata
  graph.schema.json       # Schema for validation
  hats.json               # Persona-to-tier mapping
  modules/
    N-*.md                 # Per-node protocol documents
  scripts/
    validate-graph.sh      # Graph validation script
  tests/
    run-smoke-tests.sh     # Structural smoke tests
  wiring-contract.yaml     # Expected wiring contract
  SKILL.md                 # Orchestrator protocol
  RATIONALE.md             # Design decisions and rationale

Quick start

bash 
1
2
3
4
5
6
# Via CLI
goatcs-harness forge "A skill that verifies citation accuracy in research reports"     --profile power --output ./citation-verifier/

# Via Python
from goatcs_harness import forge
forge(brief="...", profile="power", output_dir="./citation-verifier/")

Architecture

Forge is itself a harness skill — its execution follows a graph topology:

  1. N-PREFLIGHT — validate and classify the input brief.
  2. N-NORMALIZE — extract structured skill fields.
  3. N-TOPOLOGY / N-DECOMPOSE / N-CONSTRAINTS — analyze topology, decomposition, and constraints (parallel dispatch).
  4. N-AGG-DESIGN — mid-graph synthesis via TRIZ contradiction resolution.
  5. N-DESIGN-GATE — quality gate before artifact generation.
  6. N-REGISTRY / N-EDGES / N-WAVES — generate node registry, edge table, and wave plan.
  7. N-SYNTH-GRAPH — synthesize the unified graph specification.
  8. N-SPEC-ARTIFACT — render the spec document (if --spec mode).
  9. N-MODULES / N-JSON / N-SKILL-RENDER — emit per-node modules, graph.json, and SKILL.md.
  10. N-VERIFY — run the V-battery (V1-V25 verification checks).
  11. N-EMIT — atomic write of all skill files.

Profiles

Profile Description
power GoT-basic topology with best-of-3 evaluation. Highest quality.
standard GoT-basic topology. Good balance of quality and speed.
minimal Linear topology. Fast prototyping.

Design gate

The design gate (N-DESIGN-GATE) is a quality checkpoint that blocks artifact generation if the design does not meet the HC-08 quality bar. It checks:

  • Node-type coverage
  • Edge-type completeness
  • Topology consistency
  • Constraint satisfaction

Grammar

Forge understands a structured brief grammar that includes:

  • Skill name and description — what the skill does.
  • Trigger conditions — when the skill activates.
  • Input/output contract — what the skill consumes and produces.
  • Topology hints — fan-out, interview-loop, pipeline, etc.
  • Constraints — invariants, hard gates, anti-patterns.

Limitations

  • Forge cannot author skills that require the harness itself to be modified (meta-skills).
  • Forge's topology design has a quality ceiling; complex topologies may need hand-authored corrections.
  • The V-battery catches structural issues but cannot verify runtime behavior.