How roles work together
New to Praxis? Start with Getting started (Runtime, role ZIP, first session). What to type per role: Working in a session.
Praxis splits delivery into four roles. Each role owns a different artifact set. They do not share an internal API. They exchange versioned JSON handoffs plus markdown packages on disk.
BA (canon) --ba.architect.handoff--> Architect
Architect --architect.developer.handoff + change-spec.json--> Developer
Developer --developer.quality.handoff--> Quality Harness| Role | Package | What it owns | What it emits |
|---|---|---|---|
| BA | @praxis/ba | Requirements canon (markdown + git) | wp/<WP>/handoffs/ba-architect.handoff.json |
| Architect | @praxis/architect | Decisions, design package, change-spec | design/<WP>/architect-developer.handoff.json |
| Developer | @praxis/developer | Plan, code changes, verification | design/<WP>/dev/quality-handoff.json |
| Quality Harness | Quality role + local service | Selected WP review and findings | Persisted review record; approved Apply is separate |
Who talks to whom
- BA confirms vision and a work-package plan, then emits a BA→Architect handoff. Architect reads the BA-created WP and linked requirements in the same product repository.
- Architect accepts only if
visionConfirmedis true and readiness checks pass. It writes a design folder and a machinechange-spec.json, then emits Architect→Developer. - Developer accepts the design package, requires a human/CLI approve gate, applies the change-spec, runs required configured checks and records actual or skipped results, then emits Developer→Quality.
- Quality reviews a path or an MR context. It validates the Developer handoff schema and verification readiness. It does not invent acceptance criteria — it uses
acceptanceChecksfrom the handoff when present.
Roles never import each other. Shared types live in @praxis/contracts. Shared project settings live in @praxis/project-config (.project). Shared norms live in @praxis/knowledge.
Session vs CLI
In Claude Code, skills under plugins/<role>/skills/ drive the interview and file authorship. Irreversible steps still go through CLI gates (praxis-ba wp approve-plan, Architect emit, Developer --approve).
In CI / e2e, the same CLIs run without the chat UI. That is the proven machine path (npm run accept:handoff-chain, npm run smoke).
Current Desktop flow and advanced local flow
The local canon/CLI chain above has durable file gates. Its older MR preview tool does not itself publish a remote change. Current Desktop Runtime additionally supports scoped Jira preview/apply and real Git Delivery: approved commit, push, and Pull Request after Quality approval.
Developer complete leaves Jira In Progress and emits evidence. Private Quality review runs tests and records findings without Jira writes; a separate approved Apply can transition the issue to Done. See the end-to-end tutorial.
Publishing this website, DNS, and TLS remain deployment concerns, separate from the role workflow.