scriptoriumadmin/hypertwist
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
hypertwist/AGENTS.md

6.6 KiB
Raw Blame History

Repository Guidelines

Project Structure & Module Organization

UnrealHyperTwist/ is the live application root. Treat UnrealHyperTwist/Source/UnrealHyperTwist/ as the primary first-party code surface and UnrealHyperTwist/Config/ plus Content/ as the active project shell. UnrealHyperTwist/Plugins/UnrealMCPChong/ is the only maintained in-repo plugin fork; the other plugin folders are external copies and should stay untouched unless a plugin task explicitly names them. docs/ contains working documentation, while docs/refs/ is reference-only and may contain sensitive ops material. mirrors/, zippedreposource/, and the archived content folders at repo root are custody/reference storage, not the default edit target.

Build, Test, and Development Commands

Open UnrealHyperTwist/UnrealHyperTwist.uproject or UnrealHyperTwist/UnrealHyperTwist.sln in Visual Studio 2022 / Unreal Engine 5.7 for normal work. Use git -C C:\HyperTwist status --short before and after changes. The bootstrap CI check is defined in .woodpecker/hypertwist-bootstrap.yml and validates the presence of the Unreal project, source module root, and docs tree.

For Unreal C++ validation, the canonical Windows build command is:

"C:\Program Files\Epic Games\UE_5.7\Engine\Build\BatchFiles\Build.bat" UnrealHyperTwistEditor Win64 Development C:\HyperTwist\UnrealHyperTwist\UnrealHyperTwist.uproject -WaitMutex -NoHotReloadFromIDE

The governing doctrine for when this build is mandatory is:

  • C:\HyperTwist\docs\ops\HYPERTWIST_UNREAL_BUILD_VALIDATION_REQUIREMENT_2026-06-01.md

The current verified reverse-SSH Windows build lane is documented here:

  • C:\HyperTwist\docs\ops\HYPERTWIST_REVERSE_SSH_WINDOWS_BUILD_LANE_VERIFICATION_2026-06-01.md

Agent Instructions

When Visual Studio MCP tools are available, prefer semantic solution/project/document tools over raw filesystem grep for C# or Unreal symbol work. Default the working scope to UnrealHyperTwist/ and tracked repo docs before exploring mirrors or archived source material. Do not modify mirrors/, zippedreposource/, or docs/refs/ unless the task is explicitly about provenance, intake, or operations. If you encounter Rust content under mirrored dependencies, anchor analysis on the nearest Cargo.toml; do not fabricate Rust workspace files for this repo.

For Unreal C++ work, do not describe a slice as landed or fully validated from symbol checks, doc checks, or whitespace checks alone. Unless the user explicitly changes the rule, run the canonical Windows Unreal build once per logical C++ slice and say plainly whether it passed, failed, or was not run. If the build is being done through the Windows reverse tunnel, use the current verified localhost:22022 primary path documented in the verification note, and when that listener is occupied or stale use the documented verified fallback localhost:22023 path instead of guesswork or placeholder ports. The current Linux-side pickup sequence for that lane is now explicitly recorded in the sensitive runbook section 21A, including the shared VPS key staging step and the Windows password-backed connect-back command.

For HyperTwist repo evaluation, repo-custody, or license-audit work, a deep-source closeout is not complete when only the packet and root legal tracker were updated. Before calling the pass closed, explicitly check and update when applicable:

  • docs/v6_5_deep_manual_pack/HyperTwist/FEATURE_REGISTRY.md
  • docs/ops/HYPERTWIST_RETROACTIVE_AUTHORITY_AND_CLEANUP_BACKFILL_2026-05-20.md when later evidence changes a relied-on slice or backfill interpretation
  • docs/ops/HYPERTWIST_CROSS_LANE_AUTHORITY_HIERARCHY_AND_RECONCILIATION_2026-05-20.md when doctrine wording changes
  • docs/ops/HYPERTWIST_SKILLIZATION_AND_COMMAND_SURFACE_DOCTRINE_2026-05-21.md when wrapper-versus-feature or source-closed command posture changes
  • docs/REPO_LICENSE_TRACKING.md
  • docs/v6_5_deep_manual_pack/HyperTwist/LICENSETRACKING.md when policy changed
  • docs/HYPERTWIST_REPO_LICENSE_EVIDENCE_AUDIT_2026-05-27.md
  • docs/generated/license_audit/HYPERTWIST_REPO_LICENSE_EVIDENCE_AUDIT_2026-05-27.csv
  • docs/generated/license_audit/MIT_LICENSE_TEXTS_2026-05-27/ and docs/generated/license_audit/THIRD_PARTY_NOTICES_MIT_DRAFT_2026-05-27.txt when the repo resolves to MIT
  • scripts/Write-HyperTwistRepoLicenseEvidenceAudit.ps1
  • docs/ops/HYPERTWIST_UNREAL_BUILD_VALIDATION_REQUIREMENT_2026-06-01.md when Unreal build-validation posture or command changes
  • docs/ops/HYPERTWIST_REVERSE_SSH_WINDOWS_BUILD_LANE_VERIFICATION_2026-06-01.md when the verified reverse-tunnel path or proof details change

The current HyperTwist restart endpoint for this sequence is C:\HyperTwist\docs\ops\HYPERTWIST_DEEP_SOURCE_CLOSEOUT_AND_LEGAL_EVIDENCE_SEQUENCE_2026-05-26.md.

When the user says continue, interpret it as continue in logical sequence, not merely resume the nearest open task. If the user says c, apply the same rule. If two or more options are paired and one logically widens or completes the lane needed by the others, do that sequence rather than picking an isolated substep out of order. In those cases, prefer the sequence that completes both or all aligned options, except for truly negligible or irrelevant leftovers that can be deferred without distorting the packet. The default continuation target is: scope the current packet, implement it, validate it, and keep going until the safe package is ready to land unless validation fails or a real decision is required.

When continuation includes both implementation and landing work, do the widening and closure work first and commit only once the aligned package is actually ready. Do not stop after the first substep if the logical sequence clearly includes the second.

If the user says continue until the current packet is fully scoped, implemented, validated, committed, and pushed, stay on that packet until one of those states is reached or a real blocker appears. If the user instead says continue for up to n aligned steps, keep going through those aligned steps and stop only if tests fail, a real decision is needed, or the specified step budget is exhausted.

When providing a task summary, use the last paragraph to propose and display the next best clean roadmap implementation moves or the next best bounded implementation slice. That closing paragraph should be specific to the latest landed state and should not fall back to generic wrap-up text.

When a task is safely complete, stage, commit, and push it without waiting for a separate reminder. Prefer landing the full aligned package after the widening/closure work is done, rather than committing intermediate fragments that leave the intended sequence half-finished.