Bring an existing project into Praxis

Your team already has code, Confluence pages, a backlog, and a release process. Bring the requirements and current implementation into one baseline audit package. Establish what already works, where behavior deviates, and what cannot yet be verified. Then take one agreed correction through delivery without reconstructing the conversation at every handoff.

This guide covers the adoption process, from an initial snapshot through the first delivery. Each person uses their own harness. You do not need to install every role for every team member.

Define the audit and its owners

Treat adoption as one overarching audit work package: compare the agreed requirements with the current product. Name a product owner who can resolve conflicting requirements, an Architect, a Developer, and a Quality reviewer. One person can hold several responsibilities, but each handoff still needs a clear result. This audit package is a recommended team artifact, not a new built-in Runtime package type.

Agree on the audit's scope, current release or commit, relevant Confluence pages, Jira issues if used, and the existing checks required before merge. List all included areas, then review them in bounded batches under the same audit. Start with an area that is about to change or carries high risk. The examples below use invoice cancellation as that first batch. Keep the team's branch protection, review policy, and deployment process in place.

Ready to continue: the team can name the audited areas, who decides intended behavior, the first batch, and what is outside the audit. Choose the first implementation pilot after reviewing the deviations.

Put each role in the right repository

BA and Architect work in one shared product repository. BA owns product intent and the initial canonical work package; Architect adds design for that same package. A checkout means a local working copy of a repository. The canon means its versioned product knowledge; neither term implies an additional repository.

Developer works in the code repository and receives the product package and its referenced files. Quality reviews the implementation and evidence. Install each person's role using Claude Code CLI setup or Desktop installation.

flowchart TD
  S[Confluence, tickets, code and existing tests] --> R[Reviewed sources for one pilot]
  subgraph P[Shared product repository]
    BA[BA: request, requirements and initial WP]
    A[Architect: same WP, design and contracts]
    BA --> A
  end
  R --> BA
  A --> H[Explicit package handoff with referenced files]
  subgraph C[Code repository]
    D[Developer: implementation and evidence]
    Q[Quality Harness: review and findings]
    D --> Q
  end
  H --> D
  Q --> O[Human decision and existing delivery process]
  Q -->|Requirement question| BA

There are two execution paths. Choose one for the pilot and record it:

Path	What to prepare
Source local-canon workflow	Use compatible source tools. The Developer workflow supports a product/design location through --design-dir and a separate code location through --product. See the Developer playbook.
Installed Runtime workflow	Runtime uses its selected repo for package discovery, code, and tests. Prepare the supported package inputs there explicitly; it does not import them from a sibling product repository. See project configuration.

Do not transfer only the handoff JSON. Resolve its referenced requirements, contracts, design, and manifests, and record which product revision was supplied. If you combine canonical WPs with Runtime execution packages, record their ID mapping; they are different identities. See repository handoffs.

Record what “baseline” means

An existing system is evidence of current behavior, including its bugs. Importing its documents does not approve that behavior as the desired product.

Baseline	Purpose	How to establish it
Adoption snapshot	What exists before the pilot	Record code SHA, environment, document versions, current behavior, checks, known failures, and unanswered questions.
Accepted requirements baseline	What the product owner has formally accepted	Follow BA's delivery and acceptance process. In the source canon, the accept skill writes baselines; importing documents is not acceptance.
Quality history	How assessments change over time	Preserve individual review evidence. The separate private Quality Platform is planned to track multiple projects and their histories; installing Quality Harness alone does not create that platform.

An engineer can inspect the starting revision without changing files:

git -C /work/product-docs rev-parse HEAD
git -C /work/product-docs status --short --branch
git -C /work/product-code rev-parse HEAD
git -C /work/product-code status --short --branch

Replace the example paths with actual working copies. A commit SHA does not describe uncommitted changes, so record those separately. From the project's own CI configuration, identify the actual test, lint, build, and security checks. Preserve their commands, versions, exit status, scope, and output. Run checks in the team's usual test environment. Mark checks that cannot run as skipped, with a reason; do not turn existing failures into a passing baseline.

Move useful knowledge out of Confluence

Treat this as a reviewed migration of one area. The steps below are a team procedure, not a built-in Praxis Confluence importer or a bidirectional sync feature.

1. Export the selected sources

For Confluence Cloud, ask a space administrator to open Space settings → Export space, choose HTML, and select the pilot's pages. HTML export omits page comments and blog posts; separately capture relevant decisions from those sources. Exports have access and organization-policy limitations, so compare the result with your intended page list. Consult Atlassian's export instructions for the current controls. For Data Center, use the instructions for your installed edition.

Keep the original archive. HTML and XML space exports include attachments; the HTML layout groups them by page ID and preserves filenames. Check the exported files against the pages that reference them. See Atlassian's attachment export guide.

Store the raw export in a team-approved source archive with the appropriate access. Do not put an entire private space into a public documentation repository. A pilot needs the relevant product evidence, not an indiscriminate copy of company knowledge.

2. Keep a source register

Before rewriting prose, record where each item came from. This is a suggested migration record, not a harness schema:

Source: Confluence page URL and page ID
Title / owner: Cancellation rules / Product Owner
Page version: recorded version, or unknown
Exported at: date and time
Original file and attachments: archive paths
Target: proposed product document or requirement
Disposition: keep as source / draft / needs decision / migrated
Reviewed by: person and review date

Preserve source links even after migration. Record missing pages and inaccessible attachments explicitly. A page being absent from the export does not prove that the team has no documentation for it.

3. Convert to drafts, then check meaning

Ask Claude to convert the selected pages into readable Markdown drafts outside the accepted requirements. Preserve tables, units, exceptions, diagrams, and attachment references. Inspect embedded Jira results, dynamic macros, and diagram attachments manually; a text conversion alone is not evidence that they survived.

I am the BA. We are adopting Praxis for an existing project.
Pilot: cancellation of an unpaid invoice.
Product repository: /work/product-docs
Confluence export: /work/source-archive/billing

Inventory only the selected source pages and their attachments first.
Show a conversion and source-mapping proposal before writing drafts.
Preserve page URLs, recorded versions, owners and unresolved references.
Separate product requirements, technical decisions, meeting history and
outdated material. Do not turn every page into a requirement.
Flag conflicts, missing content and ambiguous rules for the product owner.
Do not approve requirements, overwrite existing canon, or publish anything.

Review every pilot document against its source before promoting its content. Keep historical discussions as evidence; turn only the agreed behavior into requirements through the BA workflow.

4. Resolve disagreements with the running system

For example, Confluence says an unpaid invoice can be cancelled, while the current API also allows cancellation after payment. Record both observations with their sources. The product owner decides whether this is a defect, stale documentation, or a requested rule change. The agent must not silently rewrite the requirement to match the code.

Observation	Evidence	Decision needed
Documented cancellation rule	Page URL and version	Is this still intended?
Current API behavior	Commit, route, test or reproduced result	Is the difference a bug?
Proposed requirement	Draft with acceptance criteria	Who accepts the intended behavior?

Find what is already implemented

Before creating new development scope, reconcile the pilot's documented behavior with the implementation. Assign an engineer to supply code evidence and the BA to interpret it against the intended behavior. This works both when Confluence contains requirements and when the team must recover context from code.

Start from a recorded code revision. Inventory the pilot's entry points: backend routes, UI actions, jobs, consumers, and external integrations where applicable. Trace the relevant paths through domain logic, persistence, permissions, feature flags, and tests. A button or endpoint name alone does not establish that a complete behavior exists.

In the source BA onboarding path, ba-code-surface-scan supports enumerating backend routes and frontend actions from the selected code anchors. Treat the scan as a bounded inventory, not an exhaustive correctness proof. Other entry points, unreadable paths, generated code, and external services require explicit follow-up. See the source BA skill inventory for availability in your setup.

Build an implementation coverage matrix. This is a proposed adoption artifact, not a new machine-readable harness contract:

Behavior or requirement	Status	Evidence and remaining work
Cancel an unpaid invoice	Implemented in reviewed scope	Recorded SHA, API handler and service path, relevant passing test; deployment still checked separately
Block cancellation after payment	Partially implemented	UI blocks it, but API path lacks the guard; propose a bounded correction
Record who cancelled the invoice	Not found in inspected scope	List searched routes, persistence paths and tests; inspect other services before claiming absence
Notify the customer	Unverified	Integration call exists, but provider behavior and environment were not checked

These rows are illustrative. Populate the real table only from your project's evidence. Add the source page or requirement ID, acceptance criterion, code revision, file and symbol references, test result, coverage limits, owner, and review date to each real row.

Use implemented in reviewed scope only when the relevant acceptance behavior has supporting evidence. Use partially implemented when a specific part is present and a specific gap remains. Use not found in inspected scope for a bounded negative finding, and unverified when access or checks are missing. Record contradicts intended behavior separately when the observed implementation conflicts with the requirement. Keep “present in code,” “tested,” “deployed,” and “accepted by the product owner” as separate facts.

We are onboarding the existing invoice-cancellation area.
Compare the reviewed Confluence requirements with the code at the recorded
revision. This is a read-only implementation audit, not a coding task.

Enumerate the relevant entry points, then trace each acceptance criterion
through the implementation and tests. Check API and UI behavior separately,
including permissions, feature flags, failure paths and stored effects.
Use the repository's existing code index where available, and inspect source
for missing coverage. State which paths and services you did not inspect.

Produce a coverage matrix with source requirement, status, code references,
tests and actual results, gaps and confidence limits. Never infer a passing
test from the presence of a test file. Do not claim system-wide absence
from a search limited to one service. Identify what is already implemented
so we do not schedule it again. Do not edit code or approve requirements.

BA and Architect review the matrix together. Reuse behavior that is already supported; make the next WP cover the agreed difference. If the existing behavior is correct but poorly documented, the first task may be documentation or missing verification rather than feature development. If desired behavior is disputed, record the product decision before calling the difference a bug. Preserve technical debt and unrelated gaps as separate follow-up work instead of silently expanding the pilot.

Ready to plan: every pilot acceptance criterion has a coverage status, evidence or an explicit unknown, and an owner for resolving gaps. The planned change explains what already exists and exactly what remains.

Ask Quality to find deviations

Use the audit package to bring together the requirements, implementation coverage matrix, source versions, code revision, architecture constraints, and actual check results. Quality should challenge the correspondence between them, not just summarize the matrix created by the first agent.

flowchart TD
  R[Reviewed requirements and source versions] --> W[Baseline audit package]
  C[Code revision and implementation map] --> W
  E[Checks, evidence and coverage limits] --> W
  W --> Q[Quality: challenge claims and run supported checks]
  Q --> F[Deviation register with evidence]
  F --> H[Human triage: intended behavior and priority]
  H --> B[Bug, requirement change, design correction or missing verification]
  B --> P[Bounded delivery WPs]

What the current Quality implementation supports

The current Runtime reviews a prepared execution WP. It reads a manifest, change-spec.json with acceptance checks, Architect handoff, Developer completion evidence, and Quality handoff. It checks identities and readiness, runs supported acceptance checks and the configured project test command, and stores the result. The reviewed source supports contains and npm-test acceptance-check types; unsupported types are blocked. A text-presence check is not proof of correct business behavior.

There is no demonstrated one-command “compare the entire repository with all Confluence requirements” operation in this implementation. A Quality session must perform the semantic audit explicitly; the Runtime review supplies the checks and persisted evidence its contract supports. A passing automated review says nothing about requirements omitted from that contract.

For an audit-only package, first inspect compatibility with the installed release. Runtime expects a Jira work-package identity, consistent package identifiers, real evidence, a Quality handoff, and readiness. Missing inputs can block review. Do not fabricate a completed implementation, set readiness by hand, invent issue keys, or weaken acceptance checks to get a passing verdict. If the audit cannot be represented through supported operations, keep the evidence-backed Quality assessment as an audit report and record the Runtime step as blocked. Use normal execution WPs for the subsequent corrections.

Prompt for the Quality session

This is a baseline audit of an existing product, not acceptance of a newly
implemented feature. Review the audit package, scoped requirement list,
Confluence source versions, recorded code revision and implementation map.

Independently check the evidence behind each claim. Find missing behavior,
partial implementation, contradictory business rules, design divergence,
permission gaps, undocumented behavior and missing verification.
For each deviation, show expected behavior, observed behavior, requirement
and code references, reproduction or check result, impact and coverage limits.
Keep unknowns distinct from confirmed defects.

Inspect whether the installed Runtime can review the prepared package using
its real manifest, acceptance checks and handoffs. Report missing prerequisites.
If compatible, ensure Quality is healthy and run praxis_quality_review.
Report its verdict separately from the broader semantic audit and include
failed, blocked and skipped checks. Do not invent missing completion evidence.
Do not modify product code, apply Jira outcomes, create bugs or merge.
Present a deviation register and proposed follow-up work for human triage.

The session may write audit evidence, and Runtime review persists local records. This is assessment work, not permission to repair the product or apply an outcome.

Turn findings into owned work

For each finding, record a stable audit ID, affected requirement and its version, expected versus observed behavior, code/test references at the reviewed SHA, severity with rationale, verification limits, proposed owner, and disposition. Keep one aggregate report across batches, including inspected and uninspected areas. A completed first batch does not mean the whole project is covered.

Finding	Next decision
Implementation violates a confirmed requirement	BA registers or links a bug; create a bounded correction WP through the normal process.
The requirement is outdated or conflicts with another source	Product owner decides intent; BA follows the change-request and requirement-versioning workflow.
Implementation conflicts with an approved technical decision	Architect reviews whether design or implementation must change.
Existing behavior has no requirement	Product owner determines whether to retain and document it, change it, or remove it.
Evidence is missing	Assign a verification task; retain an unverified status until evidence exists.

Audit completion means every item in the agreed scope has a reviewed disposition or an explicitly accepted coverage limitation. It does not mean every deviation has been fixed. Select the first correction as the implementation pilot and retain links back to this audit. The private Quality Platform's planned cross-project history is separate from this single-project adoption report.

Build the BA context and first requirements

Choose the entry point based on the evidence you have:

• Useful source documents already exist: use the BA capture-cr workflow to register the selected request and source material, then clarify its impact. ba-onboard is not the document-import workflow.
• Code exists but BA artifacts are missing: the source ba-onboard skill reconstructs project context, a glossary, shared references, and an AS-IS map. It identifies one slice, enumerates its code surface, and asks a person to validate conclusions before writing the recovered context. It then hands the slice to capture-cr.
• Your team uses the installed Runtime/Jira package: use its supported Epic analysis and preview workflow. The source skill inventory is broader than the hosted Skills ZIP; do not assume that ba-onboard is installed. Use the BA playbook to choose the supported path.

In Claude Code, open the product repository after completing role setup:

cd /work/product-docs
claude

Then describe the task and ask the harness to confirm available capabilities:

I am the BA. Inspect the installed role and report which onboarding and
requirement tools are available before acting.
Use the reviewed Confluence sources and the current-state evidence for
invoice cancellation. Keep facts, inferred behavior and unanswered product
questions separate. The product owner must resolve intent.
Register the request using the supported BA workflow, show the impact on
existing requirements, and propose one bounded WP. Reuse existing IDs.
Ask for the required decisions before confirming or accepting anything.
Do not write architecture or product code.

In the source workflow, the sequence is capture-cr → grill-cr → ba-plan-slice → shape-requirement, with the required human decisions at the applicable steps. Use prepare-wp for the initial package. See the complete BA scenarios for bugs, changed requirements, plan approval, and handoff commands.

Ready for Architect: the pilot has resolved scope, traceable requirements and acceptance criteria, an initial WP, and the required BA handoff. An unanswered product decision remains visible rather than becoming an agent assumption.

Prepare and deliver the first package

Architect: inspect gaps before designing

Open the same product repository with the Architect harness. The source workflow's intake-audit checks the BA package; context-map establishes the relevant technical landscape. Neither step authorizes inventing missing product requirements.

I am the Architect. Open the BA-created WP for invoice cancellation in
this product repository and preserve its ID.
Check the BA handoff and resolve every referenced requirement.
List missing acceptance criteria, contradictory rules and requirements
that have no design coverage. Return product questions to BA.
Inspect the existing billing service and its contracts at the recorded
code revision. Prepare design and a change specification for this WP.
Show what the Developer must receive, including referenced files, the
product revision, and any mapping to a Runtime execution package.

Follow the Architect playbook for the actual skills, readiness checks, and package outputs. Check coverage against the pilot's requirement list before handing off; a design document existing is not proof that every requirement is covered.

Developer: implement in the code repository

Prepare the source or Runtime path chosen earlier, then start the Developer session in the code workspace:

I am the Developer. Code repository: /work/product-code.
Use the prepared invoice-cancellation package and its recorded revision.
Check all required inputs and their references before starting.
Report missing files, stale contracts and assumptions that need the
Architect. Do not reconstruct requirements from the Jira title alone.
Plan the bounded change, then use the installed workflow to implement
and verify it. Compare results with the recorded starting checks.
Keep pre-existing failures and new regressions distinguishable.
Prepare completion evidence and the Quality handoff. Do not merge.

Use the Developer playbook for source CLI paths, Runtime skills, recovery, and evidence locations. In the source two-repository workflow, generated reports can be written back to the supplied design directory; agree who reviews and commits those product-repository changes.

Quality: review the result with its evidence

I am the Quality reviewer. Review the completed invoice-cancellation WP
with its requirements, code revision, completion evidence and handoff.
Compare the actual change and tests with the acceptance criteria.
Distinguish existing failures, regressions, missing checks and unresolved
findings. Show the review result before proposing application.
Do not apply an outcome, publish a branch, or merge without its required
separate approval.

Quality review writes local review artifacts. Applying an outcome is a separate operation with a preview and confirmation; Git delivery has its own approval. Follow Quality Harness and the team's existing PR/MR process. Final product acceptance belongs to the responsible person through the BA workflow.

Integrate it into normal team work

Agree on where each kind of change begins. The following is an operating agreement you can adopt; it does not imply that the tools synchronize these systems automatically.

Existing tool or practice	Integration rule
Confluence	Keep background knowledge and unmigrated areas there. For migrated requirements, add a link to the agreed authoritative version and identify its owner.
Jira or another tracker	Keep scheduling, assignment, and ticket discussion. Link the requirement, WP, design, and PR/MR. In Runtime/Jira, inspect status and preview writes before applying; reuse canonical Stories.
Product Git repository	BA versions accepted intent; Architect maintains the associated design and contracts. Both roles review changes in the same repository.
Code repository and CI	Developer implements the prepared scope. Existing required checks and reviewers stay in force; attach command results and revision-specific evidence.
PR/MR review	Use the WP's acceptance criteria and Quality findings alongside existing code review. Keep unresolved findings visible through the merge decision.
Customer feedback	BA classifies it as a bug, change to existing behavior, or new feature, then follows the corresponding requirement workflow.

Avoid two competing specifications

For each migrated document, record which location is authoritative, when that decision took effect, and who owns updates. After that point, a new Confluence comment becomes an input to BA review. It does not silently replace an accepted requirement. If Confluence must remain authoritative for an area, retain it as a source and record the exact version used in each package.

Before a new WP, check for source changes since the last reviewed version. Review the differences, update the source register, and let BA assess requirement impact. Preserve the previous version for evidence. Do not overwrite accepted artifacts with a fresh export.

If you later automate export or indexing through an API or connector, keep the same boundaries: scoped reads, page/version identity, attachment handling, explicit change review, and no automatic acceptance or reverse writes. That automation needs its own implementation and verification.

Check the pilot before expanding

• Another role can open the package without access to the original chat.
• Every pilot requirement has a source, acceptance criteria, an owner, and a recorded design coverage decision.
• The implementation coverage matrix distinguishes existing behavior, partial coverage, conflicts, and unverified areas; the WP does not duplicate functionality already supported by evidence.
• Exported tables, links, attachments, and relevant decisions have been checked; missing material is listed.
• BA and Architect use the same product repository; Developer can resolve every required input from the chosen execution setup.
• The implementation and review identify the code revision, actual checks, skipped checks, and outstanding findings.
• The team knows where the next bug or change request enters and where authoritative requirements are updated.

Review where the pilot stalled: missing source context, repeated product questions, incomplete design, or unreproducible evidence. Fix that handoff before adding another area. Track time waiting for clarification, returned packages, and time from ready scope to accepted delivery against your starting observations.

If a migration proves inaccurate, pause promotion of its drafts and return to the preserved source versions. Correct the mapping and repeat owner review. Existing delivery can continue outside the pilot while the team resolves the gap.

Continue with role sessions, the full delivery tutorial, or an existing Jira Epic.