Zoen Product Engineering

Load the doctrine

$builder-ethos

builder-ethos/SKILL.md

AGENTS.md

CONTEXT.md

CONTEXT-MAP.md

Non-negotiables

• Optimize for the fastest path to a safe production learning loop.
• Own Zoen's ontology and control plane; borrow bounded implementations instead of forking an entire product.
• Express product behavior as nouns, links, verbs, policies, and evidence.
• Route effectful or risky operations through an Action Gateway with policy evaluation, approval where required, idempotency, and an audit event. Agents do not write directly.
• Make every production change observable, testable through a public seam, incrementally deployable, and reversible.
• Prefer one working vertical slice over horizontal infrastructure built for hypothetical needs.
• Keep prototypes disposable. Reimplement validated behavior test-first before production.
• Preserve access minimization, individualized credentials, provenance, retention rules, client-owned export, and incident evidence.

Choose the flow

$setup-matt-pocock-skills

$wayfinder

$to-spec

$grill-with-docs

$research

$prototype

$prototype

$domain-modeling

$codebase-design

$design-an-interface

$improve-codebase-architecture

$to-spec

$to-tickets

$implement

$tdd

$code-review

$diagnosing-bugs

$triage

$qa

$resolving-merge-conflicts

$setup-ts-deep-modules

$setup-pre-commit

$handoff

$writing-great-skills

Delivery loop

1. Orient

1. Read repository instructions, domain docs, relevant ADRs, the current issue or spec, and recent code history.
2. Identify the real customer, desired outcome, production evidence, and next irreversible decision.
3. Confirm that issue-tracker and domain-doc conventions exist. Run

   $setup-matt-pocock-skills

   if they do not.
4. State what is known, what is assumed, and what remains a decision.

2. Collapse uncertainty

• Use

  $wayfinder

  when the route cannot fit in one context window. Resolve decision tickets, not implementation work.
• Use

  $grill-with-docs

  for human decisions. Ask one question at a time and recommend an answer.
• Use

  $research

  for facts from primary sources.
• Use

  $prototype

  for questions that require a runnable or visual answer. Record the verdict and discard the production claim of the prototype code.
• Use

  $domain-modeling

  continuously when words change. Use ADRs only for surprising, hard-to-reverse trade-offs.

3. Specify a vertical slice

$to-spec

• customer and outcome;
• story and concrete acceptance examples;
• nouns, links, verbs, and evidence affected;
• public interface and test seam;
• policy, risk class, and approval behavior;
• AgentRun and ToolCall evidence when agents participate;
• observability and value metric;
• data access, tenancy, retention, and export effects;
• compatibility, migration or parallel-run plan;
• rollback trigger and reversal path;
• explicit exclusions.

$to-tickets

4. Implement with XP

1. Agree the seam and acceptance examples for the ticket.
2. Run

   $tdd

   in red → green → refactor slices.
3. Keep the smallest useful interface and absorb complexity behind it.
4. Pair on high-risk decisions. When two humans are unavailable, use a separate navigator or reviewer agent as an approximation and keep the human accountable for product and risk decisions.
5. Integrate small changes frequently. Prefer a protected mainline with very short-lived branches over long-lived feature branches.
6. Keep the fast verification loop near ten minutes. Split fast and slow gates if the complete suite exceeds it.
7. Commit only coherent, green, reversible increments. Do not push, merge, deploy, or mutate external systems unless the user has authorized that action.

5. Review and release

$code-review

• acceptance and regression tests pass;
• typecheck, lint, build, and relevant security checks pass;
• policy and approval paths fail safely;
• writes are idempotent and auditable;
• logs contain provenance without leaking sensitive data;
• tenant isolation and least privilege hold;
• migration can run incrementally or in parallel where risk warrants;
• rollback has a tested trigger, owner, and procedure;
• dashboards or evidence can show customer and operational outcomes.

6. Learn

• Review working software with a real customer at least weekly.
• Compare expected and observed value evidence.
• Treat incidents and escaped defects as feedback. Run

  $diagnosing-bugs

  , add a regression test, and perform root-cause analysis.
• Reflect on the process regularly and change one thing at a time.
• Preserve slack; drop low-priority scope before compromising quality or sustainable pace.

Definition of done

• the customer-visible behavior works;
• acceptance evidence exists at the agreed seam;
• code and tests communicate the behavior;
• policy, approval, audit, provenance, and tenancy behavior are explicit;
• production telemetry and value measurement exist;
• migration and rollback are credible;
• documentation and domain language match the implementation;
• no hidden follow-up is required to make the slice safe.