Skill pack deliverable

Build Ed-Fi attendance, program, transcript, discipline, staff, and calendar workflows by calling the surface.

This hosted pack gives Claude, Codex, Perplexity Computer, and similar agents the exact TimeBack Ed-Fi 1EdTech contract: docs to read, credentials to use, routes to call, and local logic they must not add.

Open SKILL.md Worked example Proof replay Manifest JSON Customer website

Install

Install the whole folder, not just `SKILL.md`, so the agent can load platform adapters, deeper reference files, and the proof replay only when needed.

export ED_FI_SKILL_PACK_URL="https://platform3-andymontgomery-9773s-projects.vercel.app/ed_fi/1edtech/skill_pack"
export CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
export ED_FI_SKILL_DIR="$CODEX_HOME/skills/timeback-ed-fi-1edtech"
mkdir -p "$ED_FI_SKILL_DIR/agents" "$ED_FI_SKILL_DIR/references" "$ED_FI_SKILL_DIR/bin"
curl -fsSLL "$ED_FI_SKILL_PACK_URL/pack/SKILL.md" -o "$ED_FI_SKILL_DIR/SKILL.md"
curl -fsSLL "$ED_FI_SKILL_PACK_URL/pack/agents/openai.yaml" -o "$ED_FI_SKILL_DIR/agents/openai.yaml"
curl -fsSLL "$ED_FI_SKILL_PACK_URL/pack/agents/codex-cli.md" -o "$ED_FI_SKILL_DIR/agents/codex-cli.md"
curl -fsSLL "$ED_FI_SKILL_PACK_URL/pack/agents/claude-code.md" -o "$ED_FI_SKILL_DIR/agents/claude-code.md"
curl -fsSLL "$ED_FI_SKILL_PACK_URL/pack/agents/perplexity-computer.md" -o "$ED_FI_SKILL_DIR/agents/perplexity-computer.md"
curl -fsSLL "$ED_FI_SKILL_PACK_URL/pack/bin/proof-replay.sh" -o "$ED_FI_SKILL_DIR/bin/proof-replay.sh"
chmod +x "$ED_FI_SKILL_DIR/bin/proof-replay.sh"
for file in source-contract worked-example app-build-protocol auth-and-headers leak-check; do
  curl -fsSLL "$ED_FI_SKILL_PACK_URL/pack/references/$file.md" -o "$ED_FI_SKILL_DIR/references/$file.md"
done
"$ED_FI_SKILL_DIR/bin/proof-replay.sh"

Claude Code

Adapter notes

pack/agents/claude-code.md

Codex CLI

Adapter notes

pack/agents/codex-cli.md

Perplexity

Adapter notes

pack/agents/perplexity-computer.md

Source Of Truth

Contract

Hosted docs first

Agents read the customer website, data dictionary, architecture, surface QC, integration proof, and live implementation URL before making claims.

Complete UDM

Coverage evidence

193 canonical resources, 280 descriptor catalogs, 473 routed collections, 1166 UDM entries, and 3991 descriptor seed rows at generation time.

GAP-A1..A5

Platform behavior

Roster FKs, platform local ids, soft-delete, governed descriptors, and draft state remain surface-owned behavior.

Document	URL	Use
Customer website	customer_website	Quickstart, auth, errors, route shapes, workflows.
Data dictionary	data_dictionary	Field meanings, nullability, descriptor provenance, roster overlays.
Architecture	architecture	ITDs for complete UDM and platform gap fills.
Implementation	implementation API	Live surface calls only.

Agent Workflow

Read the customer website and relevant data dictionary entries.
Set `ED_FI_BASE_URL` and use demo or operator credentials.
Call `GET /` for live surface descriptor and route counts. In curl, use `$ED_FI_BASE_URL` without adding a trailing slash.
Use one paging mode per list: offset+limit or cursor.
Read descriptor catalogs before descriptor-dependent writes.
Send `Idempotency-Key` on writes and `If-Match` on updates, deletes, and draft promotion.
For attendance teacher marks, POST append-only daily/section events at the root descriptor's published cap (`attendanceWritePolicy.maxClientConcurrency`, currently 8) and report `ack_id` plus ETag as confirmation.
Build output from API response fields and doc links.
Run the leak check before delivering the app or report.

Surface-owned logic stays on the surface.

The pack intentionally carries no Ed-Fi processing script, UDM parser, descriptor table, roster reconciliation, ETag calculation, idempotency replay, hard-delete workaround, privacy redaction, or Alpha vocabulary transform. Its proof replay only calls the live API and asserts returned fields.

Worked Example

The worked example regenerates two resource-family proofs through live calls only: append-only attendance marks with correction/retention proof, and grades write/delete, plus route descriptor, governed descriptors, import/export jobs, and conformance evidence.

export ED_FI_BASE_URL="https://platform3-andymontgomery-9773s-projects.vercel.app/ed_fi/1edtech/implementation/api"
export ED_FI_TOKEN="$(curl -fsS -X POST "$ED_FI_BASE_URL/dev/mint?tenantId=demo" | jq -r '.token')"
curl -fsS "$ED_FI_BASE_URL" -H "Authorization: Bearer $ED_FI_TOKEN" | jq '.counts'
curl -fsS "$ED_FI_BASE_URL/ed-fi/descriptors/gradeTypeDescriptors?codeValue=Final&namespace=uri%3A%2F%2Fed-fi.org%2FGradeTypeDescriptor&limit=5&offset=0" \
  -H "Authorization: Bearer $ED_FI_TOKEN"

Open the full worked example. It tells agents what proof points to report without making them reimplement the platform.

Runnable Proof Replay

The replay check calls the live demo API and asserts the surface's own answers: root counts, attendance descriptor governance, attendance append-only create policy headers, attendance correction/soft-delete retention, grade descriptor governance, grade create/soft-delete, import/export acceptance plus cold-start-tolerant terminal job polling, and conformance evidence. The default job budget is 90 attempts at two-second intervals, and each poll prints elapsed timing for diagnosis.

export ED_FI_BASE_URL="https://platform3-andymontgomery-9773s-projects.vercel.app/ed_fi/1edtech/implementation/api"
export ED_FI_SKILL_PACK_URL="https://platform3-andymontgomery-9773s-projects.vercel.app/ed_fi/1edtech/skill_pack"
curl -fsSLL "$ED_FI_SKILL_PACK_URL/pack/bin/proof-replay.sh" -o /tmp/edfi-proof-replay.sh
chmod +x /tmp/edfi-proof-replay.sh
/tmp/edfi-proof-replay.sh

Expected result

The final JSON includes `ok: true`, `root: "module=ed_fi surface=1edtech counts=193/280/473"`, attendance and grade `edfi_local_id` values, `softDeleted: true`, completed import/export job ids, the import row count, and the three named conformance evidence IDs.

Binary Leak Check

No local schema

Complete UDM stays out

Agents call the endpoint catalog and data dictionary. They do not copy the UDM or descriptor tables.

No local state machine

Writes stay surface-owned

Idempotency, ETags, soft-delete, drafts, and imports/exports are API behaviors, not skill behaviors.

Stop on leak

Report upstream gaps

If the agent needs hidden logic to finish a job, it reports the earliest flawed upstream deliverable instead of adding code to the pack.

Pack Files

File	Purpose
pack/SKILL.md	Trigger metadata, install commands, source docs, boundaries, and standard workflow.
pack/agents/openai.yaml	Agent UI metadata.
pack/agents/claude-code.md	Claude Code install and proof-replay instructions.
pack/agents/codex-cli.md	Codex CLI install and proof-replay instructions.
pack/agents/perplexity-computer.md	Perplexity Computer upload and project-instruction guidance.
pack/bin/proof-replay.sh	Runnable live API replay for attendance, grades, and conformance evidence.
source-contract.md	Route families, counts, list contract, gap-fill behavior, Problems, provenance.
worked-example.md	End-to-end attendance and grades workflow proofs by live calls only.
app-build-protocol.md	App/report build rules and output requirements.
auth-and-headers.md	Token, header, ETag, idempotency, count, and proxy guidance.
leak-check.md	Binary no-leak gate and rollback routing.