From c8f69470e35a0474ee6025f45939c21b8dd2939e Mon Sep 17 00:00:00 2001 From: Taras Mankovski Date: Sun, 6 Sep 2026 04:43:41 -0400 Subject: [PATCH] docs: add Product Owner design rulebooks --- .agents/architect.md | 77 +++++++++++++++++- .agents/architecture-rules.md | 25 ++++++ .agents/component-descriptions.md | 131 ++++++++++++++++++++---------- .agents/product-interface.md | 39 +++++++++ .agents/product-verification.md | 31 +++++++ 5 files changed, 257 insertions(+), 46 deletions(-) create mode 100644 .agents/architecture-rules.md create mode 100644 .agents/product-interface.md create mode 100644 .agents/product-verification.md diff --git a/.agents/architect.md b/.agents/architect.md index febcfbf0..a01efc2f 100644 --- a/.agents/architect.md +++ b/.agents/architect.md @@ -20,6 +20,9 @@ outside the implementation can follow the decision on the first read. ## Responsibilities - Reconcile architecture, specifications, issues, milestones and PR stacks. +- Prepare the first interface, architecture and product-verification proposal + for each feature, then collaborate with the Product Owner where approved rules + do not settle it. - Review plans and implementations for architectural correctness, not coding style already covered by automated checks. - Identify the smallest coherent delivery order and work that can proceed in @@ -30,7 +33,79 @@ outside the implementation can follow the decision on the first read. project record. The Architect does not implement the reviewed change. It does not merge, -close, edit or comment on GitHub unless the user requests that action. +close, edit or comment on GitHub unless the user requests that action. Explicit +approval of a reusable rule authorizes the Architect to record that rule in its +rulebook, but does not authorize changes to another project artifact. + +## Product Owner collaboration + +The Product Owner leads the design of public interfaces, durable architecture +conventions and product verification. The Architect brings a concrete first +pass rather than asking the Product Owner to design from a blank page. + +Read and apply these rulebooks before finalizing a feature design: + +- [Product interface](product-interface.md) for anything a person or agent must + type or read while using XMD. +- [Architecture rules](architecture-rules.md) for lasting layers, ownership, + names, terms and reusable patterns. +- [Product verification](product-verification.md) for the behavior a feature + must show working. + +Approved rules delegate conforming decisions to the Architect. The Architect +shows the Product Owner a short inventory of those decisions and the rules that +settled them, but does not ask for approval again. Novelty, ambiguity, conflict +or an exception returns to the Product Owner through an interview. + +For an unresolved interface or architecture decision, review one item at a +time: + +1. **Current:** Show the existing surface or closest established pattern. +2. **Intent:** Explain the behavior or purpose in plain language. +3. **Assessment:** Apply existing rules and constraints, and name what remains + unsettled. +4. **Proposed:** Show the exact interface, wording or architecture decision. +5. **Feedback:** Ask one focused question about the proposal. + +## Communication rules + +1. When the Product Owner says they do not understand, stop and run the five-part understanding interview. + +When the Product Owner says they do not understand, stop the current design +discussion and run this interview before continuing: + +1. **Current:** Quote or restate what the Architect said. +2. **Intent:** Explain what the Architect meant in plain language. +3. **Reconsideration:** Explain why it was unclear in light of existing rules + and constraints. +4. **Proposed:** Give the exact replacement wording or design. +5. **Feedback:** Ask whether it now expresses the Product Owner's intent. + +Do not assume confusion is merely editorial. It may reveal unclear wording, an +unexplained concept or an unsettled product decision. + +## Maintaining rules + +Reusable rules come from explicit Product Owner approval. After an interview, +distinguish a decision local to the feature from a candidate rule. Propose the +exact candidate and where it applies; never generalize feedback silently. + +Record an approved rule immediately in the relevant rulebook and report its +exact wording and location. Each rulebook keeps rationale, examples and +constraints outside the normative rule. + +Maintained rules follow these format rules: + +1. Every maintained rule is one sentence of at most 160 characters; its Markdown list marker does not count. +2. Keep rationale, examples and constraints outside the rule. +3. Only explicit Product Owner approval promotes a feature decision into a reusable rule. +4. An approved rule delegates conforming decisions to the Architect. +5. Record an approved rule immediately in its rulebook. + +When a feature exposes existing debt, correct a surface the feature directly +changes or cannot remain coherent without. Record adjacent violations as +proposed follow-up Stories instead of expanding the feature, and never copy an +inconsistent pattern merely because it exists. ## Language diff --git a/.agents/architecture-rules.md b/.agents/architecture-rules.md new file mode 100644 index 00000000..98fa834f --- /dev/null +++ b/.agents/architecture-rules.md @@ -0,0 +1,25 @@ +# Architecture rules + +This rulebook records reusable decisions about system layers, ownership, +cross-package APIs, package responsibilities, shared terminology and patterns +future features should reuse. `architecture.md` and the specifications describe +the system itself; this file governs how new architecture is designed. + +## Approved rules + +1. Product Owner review covers system layers, ownership, cross-package APIs, package roles, shared terms and reusable patterns. +2. Local helpers and implementation structure stay delegated unless they introduce a new architectural concept. +3. Reuse established architecture, names and terminology before introducing a new pattern. +4. Do not copy an inconsistent existing pattern merely because it already exists. +5. Correct debt only when the feature changes that surface or cannot remain coherent without the correction. +6. Record adjacent debt as a proposed follow-up Story instead of expanding the feature. + +The Architect applies these rules without another approval when they settle a +design. A new concept, ambiguous fit, conflict or proposed exception returns to +the Product Owner through the interview in +[architect.md](architect.md). + +An architecture audit will expand this rulebook by interviewing the Product +Owner about the current documents and reconciling their layers, names, +terminology and patterns. Until then, sparse rules are not permission to infer a +convention from inconsistent precedent. diff --git a/.agents/component-descriptions.md b/.agents/component-descriptions.md index 47cd7044..f5e7674a 100644 --- a/.agents/component-descriptions.md +++ b/.agents/component-descriptions.md @@ -1,5 +1,9 @@ # Component descriptions +A component description follows the general product-interface rules and review +process in [product-interface.md](product-interface.md). This guide adds the +constraints specific to the description rendered beside component metadata. + A component description helps a document author decide what to type. It appears inside `xmd syntax` beside the component's forms, props, captures, `as` behavior, return contract and origin. Write it as the short practical explanation those @@ -7,41 +11,77 @@ structured fields cannot provide, not as a second reference entry. ## Rules -1. **Lead with an imperative.** Start with what the author can do: “Read or write - a file,” not “Reads and writes UTF-8 text.” -2. **Lead with purpose, not mechanism.** `` launches a coding - agent with prepared context. Terminal ownership and provider setup are - secondary details. -3. **Show a representative invocation.** Demonstrate the spelling instead of - naming a “self-closing” or “paired” form. The example is concrete and can be - copied into a document. -4. **Write for the Markdown author.** Describe observable behavior rather than - resolution, error segments, expansion boundaries or other engine machinery. -5. **Do not repeat the structured fields.** Forms, Props, Captures, `as`, - Returns and Origin already answer their own questions. Mention one only when - it explains a choice or a surprising consequence. -6. **Cut what the reader can infer.** Saying that deleting a missing file does - not error already implies that deleting it twice succeeds. -7. **Do not defend an absence.** “There are no formatting options” and “there - is no unbounded loop” make an omitted capability sound like a feature being - defended. Leave it out unless the refusal changes how the component is used. -8. **Do not answer a question nobody asked.** Do not promise that a value stays - unchanged or travels by reference unless a reasonable author would expect a - transformation. -9. **Keep behavior that changes use.** Activation conditions, placement rules, - scope, transport choices, failure behavior and preflight-only forms belong in - the description when they determine what an author writes or observes. -10. **State conditions before apparently unconditional behavior.** Explain when - `` runs before saying what happens when it runs. -11. **Name scope precisely.** Say “in its content” rather than “inside.” State - when a component reaches work performed by nested components. -12. **Prefer the exact recognizable term.** “Compared with `===`” is clearer and - more accurate than “by identity” or “by reference.” Name `` rather - than “questions” when another question component follows a different path. -13. **Use parallel descriptions for related components.** Give `` and - `` the same sentence structure so their differing failure - behavior is visible at a glance. -14. **Describe present behavior.** Avoid roadmap qualifiers such as “currently.” +1. Lead with an imperative. + + Start with what the author can do: “Read or write a file,” not “Reads and + writes UTF-8 text.” + +2. Lead with purpose, not mechanism. + + `` launches a coding agent with prepared context. Terminal + ownership and provider setup are secondary details. + +3. Show a representative invocation. + + Demonstrate the spelling instead of naming a “self-closing” or “paired” + form. The example is concrete and can be copied into a document. + +4. Write for the Markdown author. + + Describe observable behavior rather than resolution, error segments, + expansion boundaries or other engine machinery. + +5. Do not repeat the structured fields. + + Forms, Props, Captures, `as`, Returns and Origin already answer their own + questions. Mention one only when it explains a choice or a surprising + consequence. + +6. Cut what the reader can infer. + + Saying that deleting a missing file does not error already implies that + deleting it twice succeeds. + +7. Do not defend an absence. + + “There are no formatting options” and “there is no unbounded loop” make an + omitted capability sound like a feature being defended. Leave it out unless + the refusal changes how the component is used. + +8. Do not answer a question nobody asked. + + Do not promise that a value stays unchanged or travels by reference unless a + reasonable author would expect a transformation. + +9. Keep behavior that changes use. + + Activation conditions, placement rules, scope, transport choices, failure + behavior and preflight-only forms belong when they determine what an author + writes or observes. + +10. State conditions before apparently unconditional behavior. + + Explain when `` runs before saying what happens when it runs. + +11. Name scope precisely. + + Say “in its content” rather than “inside.” State when a component reaches + work performed by nested components. + +12. Prefer the exact recognizable term. + + “Compared with `===`” is clearer and more accurate than “by identity” or “by + reference.” Name `` rather than “questions” when another question + component follows a different path. + +13. Use parallel descriptions for related components. + + Give `` and `` the same sentence structure so their + differing failure behavior is visible at a glance. + +14. Describe present behavior. + + Avoid roadmap qualifiers such as “currently.” A description is complete when it states the purpose, shows how to invoke the component, and includes only the additional facts an author needs to use it @@ -49,10 +89,9 @@ correctly. ## Refinement interview -Refine a set of descriptions as an interview between the author of the current -behavior and a reader. The interview separates the contract from its wording, -lets one editorial decision become a corpus-wide rule, and prevents a bulk -rewrite from hiding factual mistakes. +Use the Product Owner interview in [architect.md](architect.md). The interview +separates the component's behavior from its wording and prevents a bulk rewrite +from hiding factual mistakes. ### Prepare the pass @@ -64,14 +103,16 @@ rewrite from hiding factual mistakes. ### Review one component -Present exactly four things: +Apply the general five-part interview with these description-specific details: 1. **Current:** quote the existing description verbatim. 2. **Intent:** explain the facts it is trying to communicate without defending the current wording. -3. **Proposed:** offer a clearer and simpler description that follows the rules +3. **Assessment:** identify what is unclear or inconsistent under the general + product-interface rules and the description rules above. +4. **Proposed:** offer a clearer and simpler description that follows the rules above. -4. **Feedback:** ask one focused question about the judgment still unresolved, +5. **Feedback:** ask one focused question about the judgment still unresolved, or ask for approval when none remains. Do not move to the next component until the reader answers. Apply an accepted @@ -79,9 +120,9 @@ description immediately and keep a visible count of completed entries. ### Carry feedback through the corpus -When an edit establishes a general rule, name it and apply it to every later -proposal. Revisit earlier descriptions when the rule affects them; do not change -an approved description silently. +When feedback suggests a reusable rule, follow the explicit promotion process +in [architect.md](architect.md). Revisit earlier descriptions when an approved +rule affects them; do not change an approved description silently. Check a disputed claim against the implementation before revising the prose. The description must remain accurate even when the most approachable wording is diff --git a/.agents/product-interface.md b/.agents/product-interface.md new file mode 100644 index 00000000..f154e530 --- /dev/null +++ b/.agents/product-interface.md @@ -0,0 +1,39 @@ +# Product interface + +This rulebook governs the words and structures a person or agent must type or +read while using XMD. Public syntax, CLI input, prompts, choices, help, +documentation, output, warnings, errors, refusals and generated artifacts shown +to people are in scope. Internal agent prompts are also reviewed because they +shape the product's output. + +Component descriptions also follow the specialized additions in +[component-descriptions.md](component-descriptions.md). + +## Approved rules + +1. Design public XMD interfaces so people understand what to write, what will happen, what it affects and what they receive. +2. Expected agent authorship never lowers the standard for human clarity. +3. Mixed human-agent surfaces are human-facing and meet the human standard. +4. Errors and refusals tell people what prevented progress and what they can do next. +5. Product Owner review covers internal agent prompts because they shape product output. +6. Show conforming interfaces and the rules that settled them without asking for approval again. +7. Review unresolved interfaces with the Product Owner one at a time. + +The first rule applies to both readings of an executable document: source a +person audits and output a person acts on. Agent flexibility does not justify +compressed, irregular, implicit or machine-oriented interfaces. + +## Feature review + +The Architect inventories every interface a feature adds or changes. The +inventory names the applicable approved rules and closest existing patterns. +Conforming interfaces remain visible in a short summary but need no new +approval. + +Review unresolved interfaces one at a time using the Product Owner interview in +[architect.md](architect.md). For a new interface, **Current** shows the closest +established pattern. **Proposed** shows the exact shape and wording together. + +Feedback applies first to the feature. When it appears reusable, the Architect +proposes a rule candidate separately. Only explicit Product Owner approval +promotes it into this file. diff --git a/.agents/product-verification.md b/.agents/product-verification.md new file mode 100644 index 00000000..fa96d86b --- /dev/null +++ b/.agents/product-verification.md @@ -0,0 +1,31 @@ +# Product verification + +Product verification describes the behavior a feature must show working. The +Product Owner leads this design for the foreseeable future. The Architect +prepares the first pass; the Planner and Implementor derive lower-level evidence +after the product behavior is approved. + +## Approved rules + +1. The Architect drafts product verification, then interviews the Product Owner to refine and approve the behavior it covers. +2. Product verification covers user journeys, observable behavior, important failures, recovery and incomplete implementations. +3. Interface and product verification approval precede finalized architecture or implementation handoffs. +4. The Architect and Planner derive lower-level tests from approved product verification without further approval. + +## Feature review + +Review one behavior at a time: + +1. Describe the behavior the feature must provide. +2. Show what a person does and observes. +3. Identify an incomplete implementation that could appear to work. +4. Propose verification that distinguishes the complete behavior. +5. Ask the Product Owner what should change. + +Product verification stays at the product level. Unit tests, boundary tests, +fixtures, runtime selection and focused commands are implementation evidence +derived afterward. + +A future corpus audit will use this interview to evaluate existing tests and +propose additional rules. Until that audit, the Product Owner continues to +approve product verification for every feature.