Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
109 lines (83 loc) · 4.61 KB

CONTRIBUTING.md

File metadata and controls

109 lines (83 loc) · 4.61 KB
Raw

Contributing To T3MP3ST

T3MP3ST needs contributions from prompt engineers, cyber operators, bug bounty hunters, red-teamers, AI-security researchers, and product-minded builders.

The best contributions make the system more capable while making its evidence and authority boundaries clearer.

The canonical repository and tracker are elder-plinius/T3MP3ST. Open issues and pull requests there against main. The project uses focused branches, squash merges, green exact-head CI, and does not permit force-pushing published review history.

High-Value Contribution Types

  • Add a tool adapter in src/arsenal/catalog.ts.
  • Add or improve a mission-family prompt pack in src/resources/.
  • Add a runbook phase with evidence requirements and exit criteria.
  • Add a local-safe demo mission in examples/demo-missions.json.
  • Add a smoke-test check in scripts/arsenal-smoke.mjs or scripts/field-drill.mjs.
  • Improve UI truth labels for preview, wired, installed, gated, synthetic, and live states.
  • Add parser support that turns tool output into structured evidence.

Adapter Checklist

Every adapter should define:

  • id, binary, and human-readable name.
  • category and mission families.
  • risk: local_read, passive, active, intrusive, credential, or dangerous.
  • execution: safe_command, receipt_required, import_only, or catalog_only.
  • networked: whether it can touch remote systems.
  • evidenceKinds: what proof the tool should produce.
  • outputFormats: expected output shape.
  • installHint and commandHint.
  • parserStatus: structured, text, or planned.
  • notes: the operational caution or value.

Prompt Pack Checklist

Prompt packs should include:

  • A sharp role frame.
  • Operating rules that bind the agent to scope and evidence.
  • Expected outputs that reviewers can inspect.
  • Escalation rules for uncertainty, scope, and dangerous actions.
  • Evidence contracts that say what must be captured before making claims.

Review Standard

Behavior changes must include outcome-oriented regression coverage. A change with no relevant tests is blocked. Changed executable lines should reach at least 50% coverage; documentation-only and metadata-only changes may mark this not applicable with a reason. Trust-boundary, scope, evidence, provider, installation, and release changes also need the focused checks for that risk.

Before opening a PR, run the same correctness gate used by CI:

npm run test:pr

For changes that affect claims, run modes, agent/tool execution, target scope, egress, redaction, reports, or benchmark artifacts, include a contribution receipt using docs/CONTRIBUTION_RECEIPTS.md.

If the API is running:

npm run arsenal:smoke
npm run field:drill

Follow the full Pull Request Delivery Guide before requesting review. In particular, run:

git diff --name-status upstream/main...HEAD

The PR must stay scoped to its title. Do not include stale-base deletions, unrelated provider/config churn, benchmark fixture removals, provenance doc removals, or safety-test removals. If the branch has drifted, recreate it from current main and reapply only the intended change.

When a contribution uses an earlier PR as notes, reference material, or a code source, say so in the Prior work and attribution section. Identify adapted paths or concepts and describe the fresh verification applied; prior review and CI do not transfer to a new head. For focused implementations derived from PR #163, thank and mention @xxmafiaxxx in both the PR body and the issue completion comment. The decomposition roadmap defines the execution order and closeout evidence for issues #171–#183.

Maintainers run npm run test:release and npm audit --audit-level=high against the exact release tag before publishing. The tag workflow creates one deterministic source ZIP, verifies it, records SHA-256 checksums, and retains a Sigstore provenance bundle. A green PR gate is necessary for review and merge, but it is not release certification.

Do not include secrets, private tracker content, unlicensed corpora, or uncoordinated vulnerability details. Use the disclosure channel in SECURITY.md for security-sensitive reports.

Style

  • Prefer clear adapters and evidence contracts over clever hidden behavior.
  • Label preview surfaces honestly.
  • Keep dangerous capability modeled, gated, and auditable.
  • Make the nontechnical path simpler without weakening the expert path.