Handoffs and data

Schemas: @praxis/contracts (packages/contracts/src/index.ts). Every role handoff has contract plus SemVer version.

Current Runtime artifacts

The Desktop/Jira path uses one selected local project root. It does not import a sibling canon repository automatically. A Jira key alone does not prepare the local manifest, design package, referenced requirements and decisions, and code context. Before Developer status/claim, explicitly make the complete execution package available at that root and record its mapping to any canon WP. It persists a BA proposal at .praxis-jira/proposals/<EPIC>.json, a local-to-Jira mapping at work-packages/<WP>/manifest.json, and the Architect package under design/<WP>/. Developer completion adds dev/completion-evidence.json and dev/quality-handoff.json. Quality Harness review persists qa/quality-review.json. Developer completion does not mark Jira Done.

See artifact reference and Work Package identities. A Runtime local WP ID can resolve to a Jira key; this is different from the BA canon's wp/ folder below. Compare IDs, linked file paths and the reviewed revision before resuming. A missing or stale file goes back to the preparing role; do not reconstruct it from Jira prose.

Repository boundary

Handoffs connect different role installations and, at the Developer boundary, different repositories.

product canon repository
  BA writes wp/<WP>/handoffs/ba-architect.handoff.json
  Architect reads it and writes design/<WP>/
  Architect writes design/<WP>/architect-developer.handoff.json
                         │
                         │ explicit local path or checked-out commit
                         ▼
code repository
  Developer changes source and tests
  Source Developer tools write `dev/` and Quality handoff under the explicit design directory
  Developer links the MR back to requirement and decision IDs

Boundary	Writer	Reader	Reader needs writer's harness?
BA → Architect	Business Analyst	Architect	No
Architect → Developer	Architect	Developer	No
Developer → Quality	Developer	Quality	No

The receiver validates the machine contract before trusting the prose. An incomplete handoff is returned to its writer; the receiving role does not repair upstream intent with its own plugin.

Advanced local-canon contracts

The following CLI paths and exact schema examples were verified against the earlier local-canon source snapshot. They remain useful for teams using that workflow, but they are not files bundled in the current skills-only Desktop ZIP. Use your pinned source release and inspect its help. The current Runtime path is documented above.

BA → Architect

File: wp/<WP-ID>/handoffs/ba-architect.handoff.jsonContract: ba.architect.handoff

Field	Meaning
workPackageId	WP id in the canon
workPackagePath	Path to the WP folder
requirementIds	At least one requirement id
visionConfirmed	Must be true for Architect intake
readinessChecks	{ id, passed, detail? }[]

Emit:

node plugins/ba/canon-graph/bin/praxis-ba.mjs wp approve-plan \
  --repo <canon> --wp <WP-ID> --plan wp/<WP-ID>/plan.md --json

# or
node plugins/ba/tools/emit-architect-handoff.mjs --repo <canon> --wp <WP-ID>

Example shape:

{
  "contract": "ba.architect.handoff",
  "version": "1.0.0",
  "workPackageId": "WP-001",
  "workPackagePath": "wp/WP-001",
  "requirementIds": ["FR-001"],
  "visionConfirmed": true,
  "readinessChecks": [{ "id": "plan-approved", "passed": true }]
}

Architect → Developer

Files:

• design/<WP-ID>/architect-developer.handoff.json — architect.developer.handoff
• design/<WP-ID>/change-spec.json — machine edits (ChangeSpecSchema, no contract field)

Handoff fields: workPackageId, designPackagePath, contextSlicePath, decisionIds[], features[] (id, title, readyForDev; optional estimateHours, dependsOn), optional platformContractIds.

All features[].readyForDev must be true before Developer run-work-package.

The design folder may live outside the code repository. Both Developer source tools resolve explicit paths, so a sibling canon checkout is supported. The source ZIP with Skills does not contain these executables. From the code checkout, with a compatible Developer source checkout available:

node <developer-source>/plugins/developer/tools/accept-work-package.mjs \
  --arch-handoff ../product-canon/design/WP-20260914-002/architect-developer.handoff.json \
  --design-dir ../product-canon/design/WP-20260914-002

node <developer-source>/plugins/developer/tools/run-work-package.mjs \
  --arch-handoff ../product-canon/design/WP-20260914-002/architect-developer.handoff.json \
  --design-dir ../product-canon/design/WP-20260914-002 \
  --product .

The source acceptance writes dev/acceptance.md under --design-dir; the runner writes plan, phase evidence and dev/quality-handoff.json there while --product identifies the code checkout to change. Review and stage those output files explicitly. The product canon and code repository keep separate Git histories; local writes do not commit or sync themselves. If referenced files are missing or changed since the reviewed handoff, return to Architect and revalidate before implementation.

Change-spec: changes[] (min 1) and features[] (min 1). Ops: edit needs match+replace; create needs content. Optional acceptanceChecks: { file, contains } or { type: "npm-test" }.

node <architect-source>/plugins/architect/tools/build-architecture-package.mjs \
  --ba-handoff <handoff.json> --change-spec <change-spec.json> \
  --canon <canon> --out design --product <product-repo>

node <architect-source>/plugins/architect/tools/emit-developer-handoff.mjs \
  --ba-handoff <handoff.json> --design-dir design/<WP-ID>

Developer → Quality

File: design/<WP-ID>/dev/quality-handoff.jsonContract: developer.quality.handoff

Required: workPackageId, mergeRequestRef, intention, requirementIds, decisionIds, verification with build / tests / lint / packageCriteria each { status, required }. Optional acceptanceChecks.

node plugins/developer/tools/run-work-package.mjs \
  --arch-handoff <product-path>/design/WP-20260914-002/architect-developer.handoff.json \
  --design-dir <product-path>/design/WP-20260914-002 \
  --product <code-path> --approve

Without --approve the implement/quality path does not run.

Quality MR context

Contract: quality.mr.context — input to praxis-quality review-mr --context, not written by a role plugin.

Includes repo path, base/head branches and SHAs, changedFiles, requirement/decision ids, optional nested quality handoff.

Check the handoff in your installed workflow

Use the Developer-only workflow for source-tool intake with two explicit roots, or the Quality-only workflow for local Runtime review. Check the WP ID, referenced files and actual evidence before moving forward. Source tool paths require a compatible source checkout and its dependencies; the hosted Skills ZIP does not include those executables.

Old monorepo acceptance commands are not part of the split role packages. An intake check, implementation completion and Quality review each prove a different boundary; none by itself demonstrates a published or merged change.