Developer harness

GitHub · praxis-developer

The Developer harness accepts a bounded design, researches the code checkout, writes an approved plan, implements phase by phase, and hands verified evidence to Quality.

What you do with it

You receive one design package, not the whole history of the product conversation. The harness checks that the package is implementable, narrows research to the accepted context slice, forces a concrete plan before code, and preserves evidence after every phase.

You are done when the code change traces back to requirements and decisions, every required check has a real result, and Quality can review the MR without reconstructing your session.

flowchart TD
  H[Architect handoff] --> A[Accept or return]
  A --> R[Research bounded code paths]
  R --> P[Write and approve plan]
  P --> I[Implement verified phases]
  I --> F[Run final arbiter]
  F --> Q[Emit Quality handoff]

Role/stage: developer / implement. Source skills/tools below extend beyond the installed Skills ZIP.

Current Desktop workflow: complete, review, then deliver

For Claude Code, start with CLI installation and the two-root Developer recipe. For Desktop, install Runtime and the Developer ZIP. The Architect ZIP is unnecessary when the complete local execution package already exists in the selected Runtime root. Runtime does not import a sibling product repository; verify manifest, design, references and canon/Jira mapping before claim. Start with Developer Status, then Claim Work Package and Implement Work Package. Runtime accepts a mapped local WP ID or its Jira key; a bare BA canon folder is not a claimable execution package.

Check Developer status for WP-20260914-002.
Show the Jira mapping, claim, handoff, change-spec, and readiness.
Prepare the claim and show START_DEVELOPMENT before asking for confirmation.
Then plan and implement only the approved scope; preserve existing changes.

praxis_developer_complete requires real verification results and explicit confirmation. It writes design/<WP>/dev/completion-evidence.json and quality-handoff.json, sets implementationState=complete and readyForQuality=true, and leaves Jira In Progress. It does not start Quality or move the issue to Done.

Quality Harness Review then executes its configured checks and persists a local result. Separate Quality Apply can mark approval and Done. After that, Git Delivery can create a snapshot-bound allowlisted commit, push the feature branch, and open a Pull Request with separate approvals. The older mr-preview-remote source tool below remains a preview tool; it is not the whole current delivery capability.

For interruption, inspect status first. Premature Done recovery has its own preview/apply gate; do not repair Jira automatically. qualityState follows praxis.state and the local manifest, not the stale status=ready-for-qa label.

Advanced local-canon playbook and source tools

The detailed skills, canon scenarios, and CLI examples below are retained from the source-verified local-canon workflow. They were verified against Praxis-mono 4eb831fd44763485ffe17307d366ffebef2f1e12. A current Desktop role ZIP contains Skills, not these source executables. Use a compatible source checkout for CLI recipes, and the current Runtime Skills above for Desktop/Jira operation.

Technical sequence

session-start → developer-status → claim-work-package when Jira is used
→ accept-work-package → research-codebase + load-stack-rules
→ classify-scale → present-design-options when applicable
→ create-plan → validate-plan + human approval
→ implement-plan / tdd → final-arbiter → mr-intention

Your boundary on the team

Install this harness in the code repository. Keep the product canon available as a separate checkout so the session can read the Architect package and write its acceptance, plan, and evidence beside that package. You do not need the BA or Architect harnesses.

workspace/
  product-canon/                  # BA + Architect artifacts
    wp/<WP>/...
    design/<WP>/...
  product-code/                   # application source and tests
    .project
    src/...

The checkouts may be siblings, a workspace with two roots, or another explicit local arrangement. These source tools are not bundled in the Skills ZIP; supply a compatible source checkout and inspect the CLI recipe. Keep each repository's Git history independent. Do not copy requirement or ADR bodies into ad-hoc code-repository notes and then treat those copies as canonical.

You receive	You own	You emit
architect-developer.handoff.json, context slice, design, decisions, change-spec.json	code changes, tests, Developer journals and evidence	MR intention and developer.quality.handoff

/session-start
I am the Developer. The code repository is <code-path>. The product canon
checkout is <canon-path>. Work Package is <WP-ID>.
Use only the Developer harness. Load .project and stack rules from the code
repository. Read the Architect package from the canon checkout. Do not mutate
requirements, accepted ADRs, or contracts.

Bring the Architect package into a code session

Pull or fetch the canon checkout to the reviewed commit before acceptance. Record that commit in your work notes. The source tools accept separate absolute or relative paths:

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

The tool writes design/<WP-ID>/dev/acceptance.md in the canon checkout. A non-zero exit or status: returned blocks planning.

/accept-work-package
Open <canon-path>/design/<WP-ID>/architect-developer.handoff.json and use its
design directory. Validate the contract before reading it as prose. Confirm:
- every in-delivery feature is readyForDev;
- index.md, context-slice.md, and change-spec.json exist;
- In slice, Out of slice, and Non-negotiables are explicit;
- every referenced decision, contract, budget, and machine file is readable.

Write the acceptance journal. If anything is missing, set status to returned,
name each blocker, and stop. Do not invent architecture and do not create a plan.

Research and plan in the code repository

After acceptance, research only inside the context slice. The plan must name real files and executable checks.

The package for <WP-ID> is accepted. Use /load-stack-rules from <code-path>,
then /research-codebase inside the accepted context slice. Cite concrete paths,
existing patterns to reuse, and risks. Escalate any necessary out-of-slice path.

Use /classify-scale and /present-design-options only when implementation choices
remain. Then use /create-plan. Every phase must include intent, exact create or
modify files, exact test or verification commands, observable Done when criteria
mapped to requirement IDs, and honest TDD order. Stop before implementation.

create-plan writes:

<canon-root>/design/<WP-ID>/dev/plan.md
<canon-root>/design/<WP-ID>/dev/plan-status.md

Validate and approve separately:

/validate-plan
Adversarially validate the plan for structure, real file paths, context-slice
compliance, executable verification, traceability, and TDD order. Write
plan-validation.md. If a check fails, return the plan for revision and do not
ask for approval. If every check passes, show me the phase summary and ask for
explicit approval. Silence is not approval.

Implement and preserve the chain

/implement-plan
Execute only the approved plan, one phase at a time. Update plan-status.md before
and after each phase. Run the phase verification exactly. On red, stop before the
next phase and enter /repair-loop with the failure evidence. On a needed decision
change, stop and use /request-architecture-deviation.

The deviation request must include workPackageId, the affected decision ID, requested deviation, reason, impact, and evidence. Conflicting implementation waits for the Architect's response.

After all phases:

Use /final-arbiter. Run the code repository's configured build, test, and lint
commands and evaluate package criteria. Preserve passed, failed, and skipped as
different states. On any required failure, repair and rerun.

When green, use /mr-intention. Write an MR description that names the product
intention, requirement IDs, decisions followed, out-of-scope work, verification,
repairs, and waivers. Emit design/<WP-ID>/dev/quality-handoff.json. Do not claim
that Quality accepted it.

For the packaged end-to-end runner, the canon/design path and product path remain separate:

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

Without approval the runner writes a pending plan and exits. Only rerun with --approve after a person has reviewed that plan.

Resume without another role's plugin

/resume-work-package
For <WP-ID>, read the claim, acceptance journal, approved plan, plan-status,
repair journal, and existing evidence. Tell me what is complete, what remains,
which gate is next, and which persisted artifact proves each answer. Do not
repeat a completed mutation.

Skill reference

Skill	Use when	Reads	Produces	Mutation / gate	Next
session-start	Begin or resume development	Repository root, .project, versions, and implement-stage knowledge	Bootstrap report for developer / implement	Read-only or advisory; no product mutation	developer-status
claim-work-package	A Jira WP is ready	Jira WP key, actor identity, and current claim state	Assignee, status, and durable claim; refuses another active owner	Writes claim/assignee state; refuses another active owner	accept-work-package
accept-work-package	Architect handoff exists	Architect handoff, design directory, and readiness fields	Acceptance journal or exact return reasons	Writes an acceptance journal or controlled return	research-codebase
research-codebase	The package is accepted	Accepted context slice and product source	Read-only research bounded by the context slice	Read-only or advisory; no product mutation	load-stack-rules
load-stack-rules	Before planning	.project, stack files, and knowledge precedence	Applicable project and knowledge rules	Read-only or advisory; no product mutation	classify-scale
classify-scale	Choose the execution path	The Architect handoff, context slice, active plan, and persisted execution state	exploratory, bounded, or architectural	Read-only or advisory; no product mutation	present-design-options
present-design-options	Implementation has meaningful alternatives	The Architect handoff, context slice, active plan, and persisted execution state	Options and previews where relevant; human selects	Writes alternatives; a human selects	create-plan
create-plan	Research is sufficient	The Architect handoff, context slice, active plan, and persisted execution state	Phased plan with checks and execution journal	Writes the named role artifact; no irreversible transition without its declared gate	validate-plan
validate-plan	Plan is drafted	The Architect handoff, context slice, active plan, and persisted execution state	Completeness validation plus human approval	Writes validation; human approval is required	implement-plan
implement-plan	Plan is approved	The Architect handoff, context slice, active plan, and persisted execution state	Product changes one verified phase at a time	Mutates product code only after persisted plan approval	tdd
tdd	Behavior changes	The Architect handoff, context slice, active plan, and persisted execution state	Red, green, refactor evidence	Mutates tests/code after a meaningful red result	final-arbiter
caveman	The fix is truly tiny and bounded	The Architect handoff, context slice, active plan, and persisted execution state	Short path that still loads scope and rules	Mutates a bounded fix; context and verification still apply	Run the final arbiter
repair-loop	A check fails	The Architect handoff, context slice, active plan, and persisted execution state	Persistent fingerprint, attempts, and escalation	Writes failure fingerprints; repeated failure escalates to a human	Retry the failed phase or escalate
request-architecture-deviation	Code cannot honor a decision or boundary	The Architect handoff, context slice, active plan, and persisted execution state	Deviation request; conflicting work stops	Writes a request and blocks conflicting work	Wait for Architect, then resume or replan
final-arbiter	Implementation phases are complete	Implemented tree, required build/test/lint commands, and package criteria	Structured build, test, lint, and package verdict	Read-only or advisory; no product mutation	mr-intention
mr-intention	Arbiter is green	Green arbiter evidence, requirement IDs, decisions, and MR intention	MR text and Developer→Quality handoff	Writes MR material and Quality handoff; this local source tool does not perform remote creation	Quality opens the evidence package
developer-status	Before claim or on resume	The Architect handoff, context slice, active plan, and persisted execution state	Read-only WP and claim state	Read-only or advisory; no product mutation	claim-work-package
plan-status	Inspect execution progress	The Architect handoff, context slice, active plan, and persisted execution state	Current phase and persisted evidence	Read-only or advisory; no product mutation	Resume the reported phase
plan-archive	Plan is finished or replaced	The Architect handoff, context slice, active plan, and persisted execution state	Audit archive and cleared active pointer	Archives state and clears the active pointer	Start the replacement plan or close the WP
resume-work-package	A session was interrupted	The Architect handoff, context slice, active plan, and persisted execution state	Restored claim, acceptance, plan, repair, and phase state	Read-only or advisory; no product mutation	Continue the persisted phase
implement-work-package	Orchestrate a Jira WP	The Architect handoff, context slice, active plan, and persisted execution state	Status, plan, approval, claim, implementation, evidence, complete	Orchestrates writes but preserves approval and claim gates	Quality reviews the completed package

Claim semantics

A materialized Runtime WP is claimable by its mapped local ID or Jira key, such as PRX-4. A BA canon folder such as wp/WP-20260914-002 alone is not. Verify the complete local package and identity mapping before claim. A claim records the actor, Jira account, timestamp, token, member set, expected state, and local state.

The same actor can resume an existing claim. Another actor must not overwrite it. Release requires explicit confirmation.

Planning gate

The plan is a product artifact, not a chat promise. It states phases, tests, acceptance criteria, scope boundaries, and status. implement-plan refuses to start until approval is persisted.

When a binding decision conflicts with reality, send a deviation request to Architect. Do not silently stretch the context slice.

Repair and verification

The source repair loop can record failure fingerprints and escalate repeated identical failures. Run the checks required by the selected package and configuration, then inspect actual executed, failed and skipped results before handing evidence to Quality.

Source tools

See CLI and recovery for every governance verb.

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

node <developer-source>/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

The Quality handoff includes the WP and MR reference, intention, requirement and decision IDs, structured check states, and optional executable acceptance checks.

Continue with Quality Harness.