Method and vocabulary

Praxis is a delivery method packaged as role-specific AI harnesses. It gives each role a defined working set, a sequence of skills, human gates for irreversible choices, and a durable artifact for the next role.

The two cycles

The delivery cycle moves one product change between people:

flowchart TD
  I[Intent] --> R[Versioned requirements]
  R --> D[Accepted decisions and design]
  D --> P[Approved implementation plan]
  P --> C[Code and evidence]
  C --> V[Quality verdict]
  V --> B[Accepted baseline]

The working cycle describes how each role handles its part:

flowchart TD
  RE[Research<br/>facts and constraints] --> BR[Brainstorm<br/>real alternatives]
  BR --> PL[Plan<br/>bounded executable work]
  PL --> IM[Implement<br/>one verified phase at a time]
  IM --> VE[Verify<br/>against requirements and decisions]
  VE -->|new fact or change| RE

Read RBPIV for the detailed loop and Roles for ownership.

Core vocabulary

How the harness operates

Term	Plain meaning	Why it exists
Harness	The skills, tools, rules, and gates given to one role.	Keeps the agent inside that role's responsibility.
Skill	A named procedure such as capture-cr or intake-audit.	Makes a session repeatable and tells it which artifact to produce.
Runtime	Shared Desktop/Cowork tools for repository, Jira, and status operations.	Performs bounded actions without putting credentials in chat.
Canon	The versioned product truth stored as Markdown plus typed metadata in Git.	Lets another session or person recover intent without chat history.
Artifact	A durable file: requirement, audit, ADR, plan, handoff, report, or evidence record.	Makes “done” inspectable.
Gate	A check that must pass before the next state or mutation.	Stops agents from treating assumptions as approval.
Human gate	A decision only a person can confirm.	Preserves ownership of vision, scope, architecture, plan approval, and acceptance.

Product and requirements

Term	Plain meaning	Typical owner or path
Vision	Why the product exists, its scope, and intended outcome.	BA · vision.md
Goal	A measurable outcome linked to requirements.	BA · goal artifact
Epic	A product slice that groups related requirements.	BA · epics/E#-slug/
CR — Change Request	A customer's request preserved verbatim, then interpreted and confirmed.	BA · cr/CR-###.md
Impact set	The exact list of existing requirements a CR amends and new requirements it spawns.	Confirmed during grill-cr.
FR — Functional Requirement	One actor's observable behavior and acceptance criteria.	BA · E#-FR#
BR — Business Rule	A reusable invariant that applies across stories.	BA · E#-BR#
NFR — Non-functional Requirement	A measurable quality constraint such as latency, availability, or security.	BA · E#-NFR#
Acceptance criterion	An observable condition that proves an FR is satisfied.	FR body; usually Given/When/Then.
Client bug	A report that shipped behavior differs from an existing requirement.	BA · bugs/BUG-###.md
WP — Work Package	The smallest coherent delivery slice, with linked CRs, delivered FRs, and constraints.	BA · wp/<WP-ID>/
Definition of Ready	Checks proving a WP is clear enough to hand to the next role.	BA gate before handoff.

Architecture and development

Term	Plain meaning	Typical owner or path
Intake audit	Architect's proof that the incoming package is complete, consistent, and feasible.	architecture/audits/
Divergence point	A place where implementers could make incompatible choices.	Architect research.
ADR — Architecture Decision Record	An accepted choice, its rule, consequences, and rejected alternatives.	architecture/decisions/ADR-*.md
Platform contract	The producer/consumer interface, errors, ownership, and compatibility policy.	Architect design artifact.
NFR budget	A quality limit with a metric, threshold, environment, and verification moment.	Architect design artifact.
Design package	The bounded explanation of what will change and why.	design/<WP>/
Change intent	Architect-authored machine description of requirements, features, files, and checks.	change-intent.json
Change spec	Validated executable form of the change intent consumed by Developer tooling.	change-spec.json
Context slice	The exact in-scope paths, out-of-scope work, decisions, and non-negotiables for one WP.	context-slice.md
Ready for development	A feature has no missing design boundary required for implementation.	features[].readyForDev: true
Acceptance journal	Developer's record that the handoff was accepted or returned, with blockers.	design/<WP>/dev/acceptance.md
Final arbiter	Executable build, test, lint, and package-criteria gate.	Developer verification.
Deviation	A formal request to change a binding architecture decision.	Developer request, Architect decision.

Handoffs and quality

Term	Plain meaning	Why it matters
Handoff	A versioned JSON contract plus linked artifacts from one role to the next.	The receiver validates it before trusting prose.
Evidence	Commands, outputs, commits, and checks that prove a result.	Replaces “the agent says it works.”
Baseline	The accepted version of requirements and delivered evidence.	Lets future changes show exactly what moved.
Quality verdict	Pass, fail, or return decision for a change based on evidence and policy.	Controls promotion before merge.
Drift	A quality or security trend moving away from the accepted baseline over time.	Shows the cumulative effect of AI coding after merge.

States are commitments

State names describe what has been proven:

stateDiagram-v2
  [*] --> Draft
  Draft --> Active: content reviewed and activated
  Active --> Batched: included in a ready WP
  Batched --> Baselined: delivery accepted with evidence
  Baselined --> Superseded: a later version replaces it
  Active --> Retired: intentionally withdrawn

Not every artifact uses every state. See the relevant role playbook for its exact state machine and CLI.

Choose your next page

• Business Analyst: shape product truth
• Architect: turn requirements into bounded decisions
• Developer: implement one approved package
• Quality: control promotion and measure drift

Runtime and delivery vocabulary

Term	Plain meaning
Runtime MCPB	One Desktop extension providing shared tools; role ZIPs contain Skills rather than additional Runtime copies.
Runtime local WP	An execution package identified by WP-… and mapped to a Jira Task in work-packages/<id>/manifest.json; distinct from a BA canon wp/ folder.
Preview fingerprint	A binding to the exact proposed mutation. Approve that plan, not an arbitrary later write.
Developer complete	Implementation and evidence are ready for review; Jira stays In Progress.
Quality Review	Local acceptance/test execution and persisted evidence; no Jira approval.
Quality Apply	Human-approved Jira mutation and local reconciliation for one persisted review.
qualityState	Current Quality approval state, separate from the WP's status label.
Quality snapshot	The reviewed file hashes used to detect drift before commit and delivery.
Git baseline	The committed starting SHA published to an empty remote; distinct from an accepted requirements baseline.

See Work Packages, approvals, and Git Delivery.