Getting Started

This page gives a new operator or developer a five-minute orientation: what ASF50 is, what it assumes, where things live, and what to do first.

What is ASF50?

ASF50 is a runtime that turns a single bounded master goal into a governed software release. It is not a model. It is not a chat agent. It is a deterministic backend with one optional AI adapter at a time, a durable runtime store, and a strict owner-gate contract.

The platform has three planes:

1. Control plane — the owner, who issues goals and approves gates.
2. Execution plane — ASF50 itself: the goal registry, the orchestrator, the program controller, the scoped owner-gate manager, the runtime store.
3. Integration plane — GitHub (PRs, CI, branch protection) and, for production, OpenSSH signed tickets.

Prerequisites

• Operating system: Windows 10+, macOS 12+, or a current Linux distribution.
• Git: any recent version with worktree support.
• PowerShell 7+ (pwsh) — the canonical operator entrypoint on Windows; bash is also supported via the Python CLIs.
• Python 3.11+ — required to run the Python orchestrator modules.
• OpenSSH ssh-keygen — required only if you will sign production tickets.
• A bounded Git working tree of an ASF50 repository.

Repository / runtime mental model

The canonical ASF50 repository lives at:

D:\Projects\ASF50-Platform\ASF50      # canonical repo
├── goals\                            # Git-tracked goal contracts (GOAL_RECORD.yaml)
├── scripts\goal-runner\              # deterministic backend (Python + PowerShell)
├── agent-harness\                    # governance, schemas, workflows, roles
├── evidence\                         # per-goal evidence receipts
├── .github\workflows\                # CI / governance / docs workflows
└── docs-site\                        # THIS documentation portal (Docusaurus 3)

The runtime root is separate from the repo. By convention ASF50 keeps it at scripts/goal-runner/local/runtime within the canonical tree for local-only development; production-grade deployments usually move it outside the repo to keep runtime state distinct from Git-tracked state.

D:\Projects\ASF50-Platform\ASF50\scripts\goal-runner\local\runtime
├── goal-state.sqlite3                # durable SQLite (read-only from CLI tools)
├── next-actions\                     # per-goal next-action records
├── runs\                             # dispatched run records
├── sessions\                         # agent sessions
├── logs\                             # execution logs
└── locks\                            # concurrency locks

Never direct-mutate the SQLite database. All persistent state changes flow through RuntimeStore and the canonical CLIs.

Canonical paths

What	Path
Goal contracts	goals/<GOAL_ID>/GOAL_RECORD.yaml
Goal context	goals/<GOAL_ID>/CONTEXT.yaml
Goal prompt	goals/<GOAL_ID>/PROMPT.md
Goal Runner Python backend	scripts/goal-runner/*.py
Goal Runner PowerShell entrypoints	scripts/goal-runner/*.ps1
Program contract	goals/ASF50_PROGRAM_COMPLETION_001/GOAL_RECORD.yaml
Evidence root	evidence/<GOAL_ID>/
Runtime DB	scripts/goal-runner/local/runtime/goal-state.sqlite3
Documentation portal	docs-site/
Governance rules	agent-harness/governance/

Five-minute orientation

1. Read the glossary (Glossary) so vocabulary doesn't surprise you.
2. Read the goal lifecycle (Goal Lifecycle) so you know the state machine.
3. Read the human gates (Human Gates) so you know where you actually have to act.
4. Read the operator handbook (Operator Handbook) so you know the day-to-day moves.
5. Skim the architecture (Architecture) for the big picture.

First operator session

After cloning the repo, run these commands (PowerShell shown; equivalent Python CLIs exist):

# Program-level read-only snapshot
.\scripts\goal-runner\program-status.ps1

# Canonical runtime root
$env:ASF50_RUNTIME_ROOT = 'D:\Projects\ASF50-Platform\ASF50\scripts\goal-runner\local\runtime'

# List all open owner gates
.\scripts\goal-runner\goal-gate.ps1 -Action list -RuntimeRoot $env:ASF50_RUNTIME_ROOT

# Status of a specific goal
.\scripts\goal-runner\goal-status.ps1 -GoalId ASF50_PROGRAM_COMPLETION_001 -RuntimeRoot $env:ASF50_RUNTIME_ROOT

Expected output: a JSON snapshot showing the program state, the current eligible IMP, the IMP progress map, and the phase-coverage map. No write happens — program-status.ps1 opens the SQLite in mode=ro.

How to inspect system status

Question	Command
What is the program doing?	.\scripts\goal-runner\program-status.ps1
What state is goal X in?	.\scripts\goal-runner\goal-status.ps1 -GoalId X -RuntimeRoot …
What gates are open?	.\scripts\goal-runner\goal-gate.ps1 -Action list -RuntimeRoot …
What does gate Y look like?	.\scripts\goal-runner\goal-gate.ps1 -Action inspect -GateId Y -RuntimeRoot …
Is the runtime split-brain?	.\scripts\goal-runner\goal-doctor.ps1 -RuntimeRoot …

How to understand a goal

A goal is the durable unit of work. The three Git-tracked files are:

• goals/<GOAL_ID>/GOAL_RECORD.yaml — the contract: goal_id, goal_type, current_state, required_role, audit_target, worktree_policy, allowed_paths, forbidden_paths, acceptance_gates, evidence_requirements, owner_gates, tasks, etc.
• goals/<GOAL_ID>/CONTEXT.yaml — human-readable metadata (runtime root, predecessor binding, scope summary, boundary summary).
• goals/<GOAL_ID>/PROMPT.md — the master goal prompt that the planner/builder role will receive.

Open goals/ASF50_DOCS_PORTAL_001/GOAL_RECORD.yaml for a live example.

Your first ASF50 goal

The canonical tutorial goal is ASF50_DOCS_PORTAL_001 — the goal that built this very documentation site. Walk through it to see a real goal go from contract to deployed docs. It demonstrates:

1. Goal materialization through GoalRegistry.materialize().
2. Bounded scaffold of a docs site.
3. Build, link check, accuracy audit, visual audit.
4. Governed commit, PR, exact-head review.
5. Governed merge and GitHub Pages deployment.

You will not need to touch the runtime DB. The orchestrator handles state.

What you should never do

• Directly edit goal-state.sqlite3. All state flows through RuntimeStore and the canonical CLIs.
• Force-push to main. Production lives behind branch protection.
• Click Merge from the chat. Only the GitHub UI merge — after the orchestrator has materialized an MERGE_APPROVAL gate at the exact head — produces a valid production-bound merge.
• Re-implement Goal Runner logic. Use the canonical CLIs.
• Embed a private key anywhere in the repo, runtime, evidence, chat, or docs. Signed-ticket trust lives outside ASF50.

What to read next

Continue to Concepts → for the vocabulary, or jump to Operator Handbook for day-to-day operations.