Architect harness
The Architect harness converts a ready requirement package into explicit decisions, measurable constraints, and a bounded Developer handoff. It does not edit product code.
What you do with it
You open a ready BA package and first decide whether it is actually designable. Then you expose the choices implementers must not make independently, compare alternatives, record only human-chosen decisions, and package the result so a Developer can work without guessing.
You are done when every incoming requirement has a visible design path, binding decisions are explicit, quality limits are measurable, and the Developer receives a bounded context slice plus a machine-readable change specification.
flowchart TD
H[BA handoff] --> A[Intake audit]
A --> C[Map context and gaps]
C --> O[Compare alternatives]
O --> D[Record chosen decisions]
D --> P[Build design package]
P --> E[Emit Developer handoff]Role/stage: architect / plan. The source playbook below includes tools beyond the installed Skills ZIP.
Current Desktop workflow: materialize one execution package
Install Runtime and the Architect ZIP. Use Plan Jira Epic and Materialize Work Package. Existing BA Stories/handoff are data; the BA ZIP is not required. The local design contains index.md, change-spec.json, and architect-developer.handoff.json under design/<WP>/ when materialized. Runtime uses its selected local root; it does not automatically import a sibling product repository.
Continue Epic PRX-1 as Architect from the canonical Stories and existing handoff.
Prepare the design and Work Package WP-20260914-002.
Preview materialization for that package only; do not create sibling packages.
Show the proposed Jira writes and wait for confirmation.Apply uses praxis_architect_apply with confirmation=YES and the exact preview fingerprint. Afterwards, praxis_work_package_show should map the local ID to the Jira Task. Keep the requirement coverage and design practices below; materialization alone does not prove that every requirement is designed.
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 → intake-audit → context-map → divergence-points
→ present-alternatives → lens-review → error-cost-gate
→ council when required → record-decision
→ platform-contract and nfr-budget as applicable
→ design-package → decompose-features → initial-estimate → context-sliceYour boundary on the team
Install this harness in the product canon repository, where it can read the BA Work Package and write architecture material. You do not need the BA or Developer harnesses. You do not rewrite requirements and you do not implement product code.
| You receive | You own | You emit |
|---|---|---|
wp/<WP>/handoffs/ba-architect.handoff.json and linked canon pages | intake audit, context maps, ADRs, contracts, NFR budgets, design/<WP>/ | design/<WP>/architect-developer.handoff.json and change-spec.json |
/session-start
I am the Architect. This workspace is the product canon repository.
List BA handoffs waiting for architecture, design packages already in progress,
open high-severity questions, and packages that are ready for Developer handoff.
Do not edit requirements or product code.Open new requirements safely
Always begin with the BA handoff, not a ticket summary. intake-audit checks contract shape, requirement completeness, contradictions, and feasibility. A failed intake goes back to the BA before design starts.
/intake-audit
Open wp/<WP-ID>/handoffs/ba-architect.handoff.json and every requirement it names.
Check completeness, contradictions, and feasibility. For each requirement verify:
- observable acceptance criteria;
- scope and stakeholders;
- links to the confirmed vision and CR;
- constraints that the design must preserve.
Write architecture/audits/<WP-ID>-intake-audit.md. If the verdict is fail,
stop and return exact requirement IDs and missing decisions to the BA.
Do not design around missing product intent.Warnings require human acknowledgement. A missing acceptance criterion or an unresolved contradiction is a failure, not an architectural assumption.
Find requirements not covered by design
Coverage is a comparison, not a feeling. Use the incoming handoff as the required set and the design package as the covered set:
- Read
requirementIds[]fromba-architect.handoff.json. - Read
requirementIds[]fromdesign/<WP>/change-intent.json. - For every incoming requirement, confirm that the design index names its outcome, an accepted ADR or explicit “no decision required” covers each divergence point, and at least one ready feature plus acceptance check carries it into implementation.
- Treat any missing ID, unresolved divergence point, absent contract, or unmeasured NFR as uncovered.
Audit architecture coverage for <WP-ID>. Treat requirementIds in the BA handoff
as the complete required set. Compare them with change-intent.json, decisions,
contracts, NFR budgets, features, and acceptance checks.
Return a table with: requirement ID, product outcome, design location, binding
decision or explicit N/A, ready feature, verification point, and coverage status.
Do not mark a requirement covered merely because its ID appears in one file.
For every gap, name the next Architect skill that closes it.When Jira is configured, /architecture-status adds read-only epic and WP state. Local artifact coverage still comes from the comparison above.
Turn the requirement package into decisions
The intake audit for <WP-ID> passed. Use /context-map, then /divergence-points.
Name affected systems, owners, existing decisions, contracts, NFRs, and unknowns.
Rank divergence points by irreversibility.
For each material point, use /present-alternatives with at least two viable
options and explicit reliability, security, cost, operations, and migration
trade-offs. Apply /error-cost-gate. Run /council when required. Recommend an
option, but wait for my decision before /record-decision. Never record an ADR
from silence.For cross-boundary behavior, use /platform-contract; both owners confirm request, response, errors, and compatibility. For quality limits, use /nfr-budget and record a metric, limit, environment, measurement method, and verification moment.
Build a Developer-ready package
Markdown alone is incomplete. design-package must include machine-readable change intent; context-slice must define what the Developer may and may not touch.
Use /design-package for <WP-ID>. Include the user-visible outcome, in-scope and
out-of-scope work, linked accepted ADRs, platform contracts, NFR budgets, and
text diagrams. Write change-intent.json with every incoming requirement ID,
deterministic changes, ready features, acceptance checks, and verification policy.
Then use /decompose-features and /initial-estimate. Ask me to accept the build
order. Finally use /context-slice: list In slice, Out of slice, Non-negotiables,
and must-read paths. Emit change-spec.json and architect-developer.handoff.json.
If any feature is not readyForDev, do not emit the handoff.The executable emitter accepts independent canon, design, and product paths:
node <architect-plugin>/tools/emit-developer-handoff.mjs \
--canon <canon-root> --wp <WP-ID> \
--design-dir <canon-root>/design/<WP-ID> \
--out <canon-root>/design --product <code-repository>The --product path is a hint for real code paths; the resulting design package remains in the same product canon repository as the BA WP. Preserve its workPackageId, review the changed scope, and pass the complete handoff plus referenced files to Developer.
Handle an implementation conflict
The Developer cannot silently drift from an accepted decision.
/accept-deviation
Open design/<WP-ID>/deviations/<deviation-id>.json. Verify the affected decision,
implementation evidence, proposed alternative, and impact. Classify the request.
If a binding rule changes, present the decision to me, record a new decision
artifact after approval, update the package and context slice, and re-emit the
Developer handoff. Keep the original ADR immutable.Skill reference
| Skill | Use when | Reads | Produces | Mutation / gate | Next |
|---|---|---|---|---|---|
session-start | Begin or resume architecture work | Repository root, .project, versions, and plan-stage knowledge | Bootstrap report for architect / plan | Read-only or advisory; no product mutation | intake-audit |
intake-audit | Open a BA handoff | ba-architect.handoff.json and readiness checks | Readiness verdict; failed intake returns to BA | Read-only gate; a failed intake returns to BA | context-map |
context-map | Intake is green | Accepted BA handoff, product topology, and knowledge rules | Systems, contexts, owners, and unknowns | Read-only or advisory; no product mutation | divergence-points |
divergence-points | Implementers could make incompatible choices | The BA handoff, current design package, .project, and applicable knowledge | Ordered decision work | Read-only or advisory; no product mutation | present-alternatives |
present-alternatives | A divergence point needs options | The BA handoff, current design package, .project, and applicable knowledge | At least two viable choices with tradeoffs | Writes option analysis; a human selects | lens-review |
lens-review | Before binding a choice | The BA handoff, current design package, .project, and applicable knowledge | Reliability, security, cost, operations, migration review | Read-only or advisory; no product mutation | error-cost-gate |
error-cost-gate | Before recording a decision | The BA handoff, current design package, .project, and applicable knowledge | Council mandatory, optional, or skippable classification | Records mandatory/optional/skippable council classification | council |
council | Error cost is high or a human requests it | The BA handoff, current design package, .project, and applicable knowledge | Multi-perspective advice; the human still decides | Writes advice; a human owns the decision | record-decision |
record-decision | An option was chosen | The BA handoff, current design package, .project, and applicable knowledge | Normalized ADR with rule and rejected alternatives | Writes the ADR after human choice and prerequisites | platform-contract |
platform-contract | Components exchange data or behavior | The BA handoff, current design package, .project, and applicable knowledge | Contract plus compatibility policy; both owners confirm | Writes a contract after both owners confirm | nfr-budget |
nfr-budget | A non-functional limit matters | The BA handoff, current design package, .project, and applicable knowledge | Metric, limit, measurement, and verification point | Writes the named role artifact; no irreversible transition without its declared gate | design-package |
design-package | Decisions are accepted | The BA handoff, current design package, .project, and applicable knowledge | Markdown design plus machine-readable change intent | Writes the named role artifact; no irreversible transition without its declared gate | decompose-features |
decompose-features | Package needs executable units | The BA handoff, current design package, .project, and applicable knowledge | Feature dependencies and readyForDev state | Writes the named role artifact; no irreversible transition without its declared gate | initial-estimate |
initial-estimate | The team needs order and scale | The BA handoff, current design package, .project, and applicable knowledge | Deterministic build order and estimate | Writes estimate/order; human accepts before materialization | context-slice |
context-slice | Prepare the Developer boundary | The BA handoff, current design package, .project, and applicable knowledge | In/out scope, non-negotiables, and handoff | Writes the Developer handoff only when features are ready | Developer opens the handoff |
accept-deviation | Developer cannot honor a binding decision | Developer deviation request and binding ADRs | Separate decision artifact; original ADR remains immutable | Writes a separate decision; binding change needs human confirmation | Return the decision to Developer |
verify-against-decisions | Implementation exists | Implemented change, ADRs, contracts, and NFR budgets | Conformance result against ADRs and NFR budgets | Read-only or advisory; no product mutation | Return findings or confirm conformance |
architecture-status | Inspect package or epic state | The BA handoff, current design package, .project, and applicable knowledge | Read-only missing-artifact and readiness report | Read-only or advisory; no product mutation | Open the missing artifact or next gate |
resume-architecture | A session was interrupted | The BA handoff, current design package, .project, and applicable knowledge | Next action reconstructed from persisted artifacts | Read-only or advisory; no product mutation | Continue the persisted design step |
grill | The architecture brief is ambiguous | The BA handoff, current design package, .project, and applicable knowledge | One-question adversarial clarification | Read-only or advisory; no product mutation | Resume the clarified architecture step |
materialize-work-package | Approved design should become Jira work | Approved local design plus explicit WP scope | Preview, fingerprint, confirmation, bounded apply | Jira mutation requires scoped preview, fingerprint, and confirmation | Developer claims the created Jira WP |
plan-jira-epic | A BA-ready epic needs technical planning | The BA handoff, current design package, .project, and applicable knowledge | Design and local Work Packages before apply | Local plan first; Jira apply is human-confirmed | Review and apply the scoped materialization |
jira-plan-epic | Use the Jira-facing planning entry | The BA handoff, current design package, .project, and applicable knowledge | Same preview and human-confirmed materialization | Local plan first; Jira apply is human-confirmed | Review and apply the scoped materialization |
Error cost and council
The error-cost gate prevents ceremonial councils for reversible choices and prevents silent decisions when rollback is expensive. The council is advisory. A person selects the option; record-decision makes it durable.
Design package
A package commonly contains:
design/<WP>/
index.md
context-map.md
context-slice.md
decisions.md
adr/*.md
contracts.md
nfr-budgets.md
change-intent.json
architect-developer.handoff.jsonMachine change operations are idempotent. An edit names matching and replacement text. A create includes complete content; an already-equal file succeeds, while conflicting content blocks rather than overwrites.
Packaged tools
The governance verbs and package builders are documented in CLI and recovery.
node <architect-source>/plugins/architect/tools/build-architecture-package.mjs \
--ba-handoff wp/<WP>/handoffs/ba-architect.handoff.json \
--change-spec <change-spec.json> --canon <canon-root> \
--out design --product <product-repo>The Developer handoff carries the WP ID, design and context-slice paths, decision IDs, feature readiness, and optional platform contract IDs. Every feature must be ready before emission.
Continue with the Developer harness.