From b30d6494dc5bad2967d16f12ceb154a181809a4d Mon Sep 17 00:00:00 2001 From: Ramesh Ayyagari Date: Sat, 30 May 2026 01:45:59 -0400 Subject: [PATCH] =?UTF-8?q?docs:=20getting-started=20guide=20=E2=80=94=203?= =?UTF-8?q?0=20minutes=20from=20clone=20to=20first=20governed=20session?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/getting-started.md | 136 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 136 insertions(+) create mode 100644 docs/getting-started.md diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 0000000..58b488b --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,136 @@ +# Getting Started + +Goal: clone the repo and run a governed agent session end to end. About 30 minutes if you already have the prerequisites installed. + +## What you need +- Node.js 18 or newer +- PostgreSQL 15 or newer running locally or on a host you can write to +- Git + +## 1. Clone and install (2 minutes) + +``` +git clone https://github.com/rayyagari2-create/agentic-workforce-framework +cd agentic-workforce-framework +cp .env.example .env +npm install +``` + +`npm install` resolves the workspace packages under `services/`, `examples/` and `packages/`. There is no build step. + +## 2. Configure the database (3 minutes) + +`.env.example` ships with five variables: + +``` +DATABASE_URL=postgres://postgres:password@localhost:5432/awf +AUDIT_SERVICE_URL=http://localhost:3001 +AWF_WORKSPACE_ID=workspace-default +AWF_TENANT_ID=awf-demo +AWF_DIVISION_ID=division-default +``` + +If your local Postgres uses trust auth for your shell user (the Homebrew default on macOS), change the first line to: + +``` +DATABASE_URL=postgres://localhost:5432/awf +``` + +Otherwise leave the user and password in and make them match your Postgres setup. + +Create the database: + +``` +createdb awf +``` + +Run the schema migrations: + +``` +npm run demo:setup +``` + +You should see 8 migrations printed, each prefixed `ok`, ending with `Setup complete. Run: npm run demo`. The setup script applies migrations 001 through 008. Migrations 009 and 010 are present in `database/migrations/` but are not part of the public demo path. + +The demo wipes the work queue at the start of every run, but never touches `audit.events`. That table is append-only by schema. If the hash chain ends up in an inconsistent state across runs (for example after a crashed demo), step 9 below will report a chain break. The fix is to drop the database and re-run setup: + +``` +dropdb awf && createdb awf && npm run demo:setup +``` + +## 3. Run the governance demo (5 minutes) + +``` +npm run demo +``` + +This is a single Node process that walks the nine Sprint 0 steps against your database. It spawns its own audit service on `127.0.0.1:8787` and sends it `SIGTERM` on exit. + +What it does: + +1. Loads 5 sample work items from `examples/awf-demo/sample-backlog.json` into `public.work_queue_items`. +2. Classifies them with the label-based rule table in `services/governance/src/classifier.js`. Each item gets a `task_class` and a `risk_level` of `LOW`, `MEDIUM` or `HIGH`. The classifier is single-pass label matching; the richer multi-dimensional Task Risk Profile lives in the control plane and is not part of this demo. +3. Claims the highest-priority eligible item using `SELECT FOR UPDATE SKIP LOCKED`. +4. Because the claimed item is HIGH risk, the approval gate writes an `approval_requests` row and the demo auto-approves it. +5. Routes the task class to a role and pins an agent instance. +6. Runs the `SimulatedRuntimeAdapter`. Every artifact is prefixed `[PREVIEW]`. The real runtime adapters are private. +7. Produces a QA verdict. Simulated runs always collapse to `pass_with_notes`. +8. Computes D1 through D4. D1 (correctness) and D2 (observability) are candidate scorers; D3 (policy) and D4 (recurrence) are deterministic. Against the simulated artifacts a fresh run scores `total=68 -> trust_level=RESTRICTED`. +9. Shells out to `awf audit verify`, which recomputes the hash chain over `audit.events` and prints a per-runtime breakdown. The last line of step 9 reads `VERIFIED`. + +What is real and what is not: the scorer code paths and the audit chain are real. The runtime evidence the scorers consume is produced by the simulated adapter, so the numbers reflect that adapter and not a live agent. + +## 4. Run the authorization demo (2 minutes) + +``` +npm run authorize:blocked +npm run authorize:authorized +npm run authorize:supervised +``` + +Each command runs `tools/authorize-task/authorize-task.js` against a different task class, risk lane and runtime, and prints a decision: `BLOCKED`, `AUTHORIZED` or `SUPERVISED + controls`. + +Without a `--db` flag the tool renders example data and says so: `Source: example data (set AWF_DATABASE_URL for live data)`. To read the trust profile your demo run actually wrote: + +``` +node tools/authorize-task/authorize-task.js \ + --task-class payment_integration \ + --runtime claude_code \ + --workspace awf-demo \ + --db postgres://localhost:5432/awf +``` + +The tier you see should match what step 8 of the demo wrote (RESTRICTED for the simulated `payment_integration` run on a fresh DB). + +## 5. Govern your first real agent session (20 minutes) + +The hooks in `hooks/` implement the Claude Code hook protocol. Cursor has no equivalent PreToolUse interception layer today, so this walkthrough uses Claude Code. The sanitized example settings file is `hooks/claude-code-settings.example.json` and the long-form explanation is `hooks/claude-code-settings-README.md`. Read both before merging anything into your real settings. + +The example wires three hook points on the `Agent` matcher: `PreToolUse`, `SubagentStart` and `PostToolUse`. + +Install the hooks into the repo you want to govern: + +``` +cd /path/to/your/repo +mkdir -p .claude/hooks/pre-tool-use .claude/hooks/sub-agent-start .claude/hooks/post-tool-use + +cp /path/to/agentic-workforce-framework/hooks/pre-tool-use/check-agent-spawn.example.js \ + .claude/hooks/pre-tool-use/check-agent-spawn.js +cp /path/to/agentic-workforce-framework/hooks/sub-agent-start/check-subagent-start.example.js \ + .claude/hooks/sub-agent-start/check-subagent-start.js +cp /path/to/agentic-workforce-framework/hooks/post-tool-use/check-agent-spawn-result.example.js \ + .claude/hooks/post-tool-use/check-agent-spawn-result.js +``` + +Then merge the contents of `hooks/claude-code-settings.example.json` into your `.claude/settings.json`. + +Start a Claude Code session in that repo and ask it to spawn an Agent. The PreToolUse hook fires before the spawn, validates the sidecar manifest against the `ALLOWED_AGENT_ROLES` roster, and either allows the call (`exit 0`) or hard-blocks it (`exit 2`). + +These hooks ship as templates. Paths like `.agent-workspace/bulletin.md` and `.agent-workspace/locks/` in the scripts are placeholders. Point them at real files in your project before relying on the enforcement. + +## 6. What to read next + +- `docs/task-risk-profile.md` for how the risk classifier works and where it is going +- `docs/d1-d4-scoring.md` for what each dimension measures and the candidate vs deterministic split +- `docs/execution-substrates.md` for where AWF sits relative to Cursor, Claude Code and Codex +- `schemas/v1/` for the JSON schemas of the governance artifacts the demo writes