Aleph Skill

Evidence-grounded timeline simulation for agents that need to reason from one change point across counterfactual pasts, alternate presents, and branching futures.

Vietnamese overview: README.vi.md

Aleph Skill turns a “what if?” into an auditable scenario model: evidence becomes typed causal structure, executable traces, and alternative timelines with explicit uncertainty and calibrated likelihood only when justified.

It has one host-neutral core. Codex, OpenCode, Claude Code, Agent Skills, Gemini CLI, Copilot CLI, Cursor, VS Code, Windsurf, Cline, Roo Code, and JetBrains can load native skill directories. Continue uses a generated project rule. Grok Build, Aider, and generic CLIs use declarative adapter profiles implemented by their host or wrapper.

At a glance

When to use it

Use Aleph Skill when an agent needs to:

• reconstruct an observed baseline before a point of change;
• simulate how a past divergence could alter a later present;
• project a present-day intervention into multiple future branches;
• model policy, market, geopolitical, social, climate, technology, or institutional scenarios;
• map butterfly effects through causal chains, thresholds, feedback loops, and lagged consequences;
• reason about public-role human decisions without turning private speculation into fact;
• produce a decision-grade report that separates fact, inference, simulation, and counterfactual.

Do not use it to claim one future is certain, profile private people, deanonymize people, bypass access controls, or collect sensitive personal information.

Product scope

This repository is a portable Agent Skill package, not a hosted forecasting service, public Python API, API server, crawler, or benchmark leaderboard. Its installable Python module is an internal, versioned execution helper rather than a stable third-party library surface.

An agent reads SKILL.md as the entry point, then loads only the reference files and templates needed for the scenario. The local helpers initialize and migrate workspaces, import signed research, compile/run/replay models, execute sensitivity and hindcast checks, validate domain packs and artifacts, render reports, finalize receipts, and verify the distributable package. They support the workflow; they do not replace the agent’s reasoning.

From 2.1.0, D Research is bundled as a locked internal component (aleph-component://d-research under components/d-research/). Hosts install only aleph-skill; nested D Research is not a second skill. Research runs through scripts/research_gateway.py with a browser → host-browser → fetch → search → blocker capability ladder. Optional Node/Playwright/browser binaries are not shipped and are not auto-installed. If capabilities are missing, Aleph builds a provenance-rich evidence map with host tools or emits structured blockers, caps assurance at limited, and never fabricates a signed ledger. See THIRD_PARTY_NOTICES.md and component-lock.json.

External-CLI profiles describe version probes, bootstrap instructions, capability boundaries, isolation requirements, and receipt expectations. Installing one does not create subagents, tool isolation, or orchestration by itself; the selected host or wrapper must implement and attest those controls.

Workflow lifecycle

Core capabilities

1. Retrospective counterfactuals — simulate how a historical divergence could change a later historical state.
2. Prospective interventions — treat the current baseline as fixed and project future outcomes from a new intervention.
3. Hybrid projections — carry a past divergence into an alternate present, then branch into future scenarios.
4. Adaptive depth — expand research and validation according to scenario complexity rather than fixed speed profiles.
5. Mechanism-first causality — reject edges that lack a plausible transmission channel, lag, context, and evidence.
6. Human-node discipline — use public-role information for actor dossiers and label all roleplay as simulation.
7. Future monitoring — attach leading indicators and disconfirming conditions to prospective branches.
8. Professional reporting — report likelihood mode, evidence quality, causal architecture, sensitivity, unresolved mass, limitations, and audit receipts.
9. Portable validation — enforce referential integrity across evidence, nodes, edges, actors, branches, traces, and reports.

Repository layout

aleph-skill/
  SKILL.md                  # agent entry point
  AGENTS.md                 # concise agent-framework instructions
  README.md                 # public overview
  README.vi.md              # Vietnamese overview
  LICENSE                   # CC BY-NC 4.0
  THIRD_PARTY_NOTICES.md    # bundled-component attribution
  agents/openai.yaml        # Codex UI metadata
  adapters/                 # runtime-specific notes
  component-lock.json       # D Research identity, recipe, and content lock
  components/d-research/    # locked internal D Research component
  examples/                 # forward-test prompts and example artifacts
  references/               # workflow, safety, causal, reporting, and research guides
  scripts/                  # stdlib-first validation and rendering helpers
  templates/                # JSON/CSV/JSONL artifact starters
  package.json              # local verification scripts
  pyproject.toml            # Python project metadata

Install

Clone the repository:

git clone https://github.com/d-init-d/aleph-skill.git
$env:ALEPH_SKILL_ROOT = (Resolve-Path ".\aleph-skill").Path

For POSIX shells, set the same absolute convention with export ALEPH_SKILL_ROOT="$(cd aleph-skill && pwd)". Native hosts resolve the directory containing SKILL.md; project adapters normally resolve <project>/.aleph/core/aleph-skill. Aleph helpers never depend on the process working directory.

Dry-run adapter installation:

python "$env:ALEPH_SKILL_ROOT\scripts\install_adapters.py" --target codex --scope user --dry-run
python "$env:ALEPH_SKILL_ROOT\scripts\install_adapters.py" --target claude-code --scope user --dry-run
python "$env:ALEPH_SKILL_ROOT\scripts\install_adapters.py" --target opencode --scope user --dry-run
python "$env:ALEPH_SKILL_ROOT\scripts\install_adapters.py" --target agents --scope user --dry-run

Gemini CLI uses its native Agent Skills directories:

python "$env:ALEPH_SKILL_ROOT\scripts\install_adapters.py" --target gemini-cli --scope user --copy

Native skill targets install the verified package in their declared skill directory. Continue and external-CLI adapters are project-scoped: their installer copies the selected rule/profile and the same verified core to .aleph/core/aleph-skill, then writes one combined receipt. External profiles remain adapter contracts rather than turnkey orchestration.

python "$env:ALEPH_SKILL_ROOT\scripts\install_adapters.py" --target cursor --scope project --project-dir <project> --copy --receipt <project>\.aleph\install-receipt.json
python "$env:ALEPH_SKILL_ROOT\scripts\install_adapters.py" --target grok-build --scope project --project-dir <project> --copy --receipt <project>\.aleph\install-receipt.json

Supported install locations:

Verification

When upgrading an existing 2.0.0 workspace, keep an untouched backup and run draft validation first. Aleph 2.1.x keeps schema_version: 2.0.0, but its stricter component binding, likelihood, privacy, and sealed-roleplay contracts can require report, packet/receipt, and numerical-artifact regeneration before final validation succeeds. For a workspace that still stores an absolute D Research path, run python "<ALEPH_SKILL_ROOT>/scripts/migrate_workspace.py" --source <workspace> --bind-bundled-d-research --check, inspect the byte-equivalence report, then repeat without --check. Do not use the 1.x schema migrator or hand-edit hashes.

Run the local release gate:

python "$env:ALEPH_SKILL_ROOT\scripts\validate_skill_package.py" "$env:ALEPH_SKILL_ROOT"
python "$env:ALEPH_SKILL_ROOT\scripts\validate_simulation_artifacts.py" --examples
python "$env:ALEPH_SKILL_ROOT\scripts\preflight.py" --json
npm --prefix "$env:ALEPH_SKILL_ROOT" run self-test

Maintainers can then build the deterministic, distribution-manifest-exact release assets:

npm --prefix "$env:ALEPH_SKILL_ROOT" run release:build

For a completed simulation workspace:

python "$env:ALEPH_SKILL_ROOT\scripts\validate_simulation_artifacts.py" --workspace <run-dir> --mode draft --write-report
python "$env:ALEPH_SKILL_ROOT\scripts\render_simulation_report.py" --workspace <run-dir>
python "$env:ALEPH_SKILL_ROOT\scripts\validate_simulation_artifacts.py" --workspace <run-dir> --mode final --require-report --write-report
python "$env:ALEPH_SKILL_ROOT\scripts\evaluate_simulation_quality.py" --workspace <run-dir> --threshold 90 --enforce

Example prompt

Use $aleph-skill to simulate an oil price +40% shock, with both the observation cutoff and shock start set to 2026-06-01.
Focus on inflation, central-bank reaction, growth, shipping, and emerging markets over 24 months.
Use the bundled D Research component through Aleph's gateway, falling back to limited host-native evidence only when the gateway reports a missing capability; keep sourced actor dossiers separate from simulated decisions,
and produce at least three branches with relative weights, indicators, contradictions, and uncertainty warnings.

Safety boundary

Aleph Skill is for lawful, evidence-backed scenario analysis. It refuses or narrows requests involving private-person profiling, doxxing, stalking, minors, private accounts, access-control bypass, captcha evasion, paywall bypass, or unsupported claims about sensitive personal traits.

It does not predict the future. It builds transparent, source-aware simulations so users can inspect assumptions, mechanisms, uncertainties, and alternatives.

License

Source-available for non-commercial use under the Creative Commons Attribution-NonCommercial 4.0 International License.

SPDX-License-Identifier: CC-BY-NC-4.0