Skip to content

getting-started.md

Latest commit

 

History

History
99 lines (75 loc) · 3.18 KB

getting-started.md

File metadata and controls

99 lines (75 loc) · 3.18 KB
Raw

Getting started

This walkthrough runs PKR from source and closes one repository-native work loop in a disposable Git repository. No Provider process is required.

Prerequisites

  • Node.js 24 or newer;
  • Python 3.11;
  • Git;
  • PowerShell for the commands below.

Build PKR

From the PKR checkout:

npm ci
python -m pip install --requirement conformance/requirements.txt
npm run verify
$Pkr = (Resolve-Path .\dist\cli.js).Path

npm run verify generates the v0.4 schemas, runs all conformance validators, builds the TypeScript Runtime, runs its regression tests, and checks the local npm package contents.

Create a disposable target

$Target = Join-Path $env:TEMP "pkr-quickstart"
New-Item -ItemType Directory -Force $Target | Out-Null
Set-Location $Target
git init -b main
Set-Content .gitignore ".pkr/"
Set-Content README.md "# PKR quickstart target"
git add .
git -c user.name="PKR Quickstart" `
  -c user.email="pkr@example.invalid" commit -m baseline

Use a new path or remove the old disposable directory yourself before rerunning the walkthrough. PKR initialization fails closed rather than replacing an existing Runtime.

Initialize and request work

node $Pkr init --project $Target --name quickstart `
  --outcome "Complete one governed local task"
node $Pkr setup --project $Target --quickstart
node $Pkr doctor --project $Target

$Card = node $Pkr run --project $Target `
  --request "Produce one quickstart result" | ConvertFrom-Json

setup --quickstart copies only verification.json and verify.mjs into the initialized .pkr/ directory. They are demonstration fixtures, not a production acceptance policy. Replace them with project-specific checks before using PKR for real release decisions.

Claim, edit, and submit

$Agent = node $Pkr agent register --project $Target `
  --name current-agent --host agent-host | ConvertFrom-Json

$Claim = node $Pkr lps claim --project $Target `
  --task $Card.taskId --agent $Agent.value.metadata.id `
  --session-locator "agent-host://current-session" | ConvertFrom-Json

node -e "require('node:fs').mkdirSync('src',{recursive:true});require('node:fs').writeFileSync('src/pkr-quickstart-result.txt','PKR quickstart work completed\n')"

node $Pkr lps submit --project $Target `
  --assignment $Claim.assignmentId --agent $Agent.value.metadata.id `
  --outcome partial

The file write stands in for an already loaded Agent editing the target repository with its normal tools. lps submit captures before/after Git evidence and records a non-authoritative work report. A session locator is correlation metadata, not identity or authority.

Verify and inspect

node $Pkr verify --project $Target `
  --task $Card.taskId --assignment $Claim.assignmentId
node $Pkr status --project $Target
node $Pkr lps board --project $Target

Only verify runs the configured repository checks and can supply acceptance evidence. A failed Verification preserves the failure and blocks the Task; it does not silently convert the work report into success.

For readiness semantics, a project-specific Verification plan, and optional Adapter execution, continue with the Runtime guide.