diff --git a/README.md b/README.md index ea049b2..f0dde47 100644 --- a/README.md +++ b/README.md @@ -9,12 +9,20 @@ Codex skills maintained by IgnitionAI. Collaborative application architecture design through Socratic brainstorming. This skill produces architecture specifications and diagrams only: domain models, database diagrams, layered architecture blueprints, stack decision records, -API contracts, ADRs, and validation checklists. +API contracts, ADRs, Product Truth Contracts, and validation checklists. + +### product-truth-gate + +Defines and enforces an observable product-outcome contract before a feature, +application, integration, migration, or repair can be declared usable or done. +It distinguishes architecture and internal checks from a verified end-to-end +user journey, and supports same-scenario parity checks against a reference. ## Installation ```bash python /path/to/install-skill-from-github.py --repo IgnitionAI/skills --path app-architect-brainstorm +python /path/to/install-skill-from-github.py --repo IgnitionAI/skills --path product-truth-gate ``` After installation, restart Codex to pick up the skill. diff --git a/app-architect-brainstorm/SKILL.md b/app-architect-brainstorm/SKILL.md index 4d5e183..51d17a8 100644 --- a/app-architect-brainstorm/SKILL.md +++ b/app-architect-brainstorm/SKILL.md @@ -1,22 +1,15 @@ --- name: app-architect-brainstorm description: > - Collaborative application architecture design through Socratic brainstorming. - Produces complete architecture specification packages: domain models, UML database diagrams, - layered architecture blueprints, component specifications, technology stack recommendations, - architecture decision records, and UI/UX design prototypes (static HTML mockup pages). - Covers all application archetypes: web apps, mobile apps, - API-only services, ML/inference APIs, desktop, real-time systems, CLI tools. - Framework-agnostic and language-agnostic — the stack emerges from requirements. - This skill produces SPECIFICATIONS, DIAGRAMS, AND STATIC HTML DESIGN MOCKUPS ONLY. - It does not generate production source code, boilerplate files, or executable artifacts. - HTML mockups are design artifacts (one self-contained page per key screen), never - production front-end code. The output is a comprehensive architecture - document package that serves as the blueprint for implementation. - Triggers on: architecture, system design, database modeling, clean architecture, DDD, - tech stack selection, project structuring, how to structure my app, design my backend, - plan my architecture, model my domain, UI design, UX design, mockup, prototype, - wireframe, design my frontend, design my screens. + Design greenfield or existing application architecture through Socratic + brainstorming. Produces framework-agnostic specification packages with domain + models, database and architecture diagrams, API and component contracts, + stack decisions, ADRs, product-truth contracts, guardian rules, and static HTML + UI/UX mockups. Covers web, mobile, API, ML, desktop, real-time, CLI, and data + systems. Use for architecture, system design, database modeling, DDD, stack + selection, project structure, reverse engineering, UI/UX flows, mockups, or + prototypes. Produces specifications and static design artifacts only, never + production code, boilerplate, configuration, or executable projects. license: MIT --- @@ -38,6 +31,7 @@ Collaborative architecture design through structured Socratic brainstorming. Age | Architecture Decision Records | Markdown | ADR-xxx for each significant decision | | Component Specification | Markdown | Per-component responsibilities and interfaces | | Architecture Contract | Markdown | Machine-verifiable rules for the project | +| Product Truth Contract | Markdown | Observable critical journey, runtime topology, failure signals, and future E2E proof | | Guardian Checklist | Markdown | Validation rules to prevent architectural drift | | UI/UX Design Package | Static HTML pages | One self-contained mockup per key screen + user flows, screen inventory, design tokens | @@ -65,6 +59,7 @@ When the user has no existing codebase — designing a new application. ``` Phase 1: Domain Discovery → Business model, entities, constraints, archetype +Phase 1.5: Product Truth → Observable outcome contract and required runtime topology Phase 2: Stack Selection → Language, frameworks, databases (evidence-based) Phase 3: Database Modeling → ER diagram (Mermaid), relations, access patterns Phase 4: Architecture Design → Layers, components, services, API design @@ -80,6 +75,7 @@ When the user provides an existing codebase — analyze, document, and plan migr Phase R1: Codebase Discovery → Understand what exists (files, deps, patterns) Phase R2: Architecture Mapping → Map files to layers (or identify no layers) Phase R3: Violation Detection → Find anti-patterns, coupling, leaks +Phase R3.5: Product Truth → Reconstruct the real runnable journey and its topology Phase R4: Architecture Blueprint → Produce diagrams of the AS-IS state Phase R5: Migration Plan → Roadmap to TO-BE Clean Architecture ``` @@ -137,6 +133,8 @@ Challenge the domain understanding before any technical decision: 8. **"What is the scale in 6 months? Users, requests/day, data volume?"** 9. **"What is the team size and experience?"** 10. **"What is the budget for infrastructure?"** +11. **"What exact sentence may we say only when the product truly works?"** +12. **"What is the first meaningful action after the initial screen or response?"** ### Step 1C: Extract the Domain Model @@ -153,6 +151,31 @@ Reference: [references/brainstorming-method.md](references/brainstorming-method. --- +## Phase 1.5: Product Truth Contract + +Architecture quality and product success are separate claims. Before selecting +the stack, define one Product Truth Contract per P0 critical journey: + +- actor and intended starting state; +- exact trigger, observable outcome, and first meaningful continuation; +- complete required runtime topology (UI, APIs, workers, stores, queues, + assets, auth, external systems, configuration); +- concrete failure signals; +- forbidden substitutes such as mocks, manual database edits, hidden setup, + skipped services, or product-specific patches outside the intended workflow; +- one planned deterministic E2E test that can fail on the user's exact symptom; +- a same-scenario parity bar when a reference product is named. + +Trace every required topology item to a component and operational owner in the +later architecture. This phase produces a specification only and must end in +state `architected`, never `product_verified`. + +When available, use `product-truth-gate` during implementation and validation +to execute this contract. The architecture package must remain usable without +that skill by containing the full contract itself. + +--- + ## Phase 2: Stack Selection (Evidence-Based) ### The Rule @@ -369,8 +392,9 @@ Reference: [references/ui-ux-design.md](references/ui-ux-design.md) — **read i 5. **Stack Decision Record**: Justified choices with rejected alternatives 6. **ADR files** (from template): One per significant decision 7. **Architecture Contract**: Machine-verifiable rules for the project -8. **UI/UX Design Package** (UI archetypes only): HTML mockups gallery, user flows, screen inventory, design tokens -8. **Guardian Checklist**: Rules to prevent drift during implementation +8. **Product Truth Contract**: P0 journey, topology, failure signals, forbidden substitutes, planned E2E proof +9. **UI/UX Design Package** (UI archetypes only): HTML mockups gallery, user flows, screen inventory, design tokens +10. **Guardian Checklist**: Rules to prevent architectural and product-proof drift during implementation ### Architecture Contract @@ -391,6 +415,9 @@ Provide the implementation team with: - Verification commands (grep patterns to check layer boundaries) **Note**: The guardian validates the implementation against this architecture contract. It does not generate code. +It must also reject completion claims whose Product Truth Contract has not been +executed at the required proof level; architecture checks cannot substitute for +that future runtime evidence. --- @@ -408,6 +435,9 @@ Provide the implementation team with: | **UI designed with lorem ipsum** | "Show me the real longest value. Does the layout survive it?" | | **No empty/error states** | "Zero items is the FIRST thing a new user sees. What does the API-down screen look like?" | | **UX skipped for a UI archetype** | "You specified an interface layer without knowing what users see. Mock the key screens first." | +| **Internal-green means product-done** | "Which Product Truth Contract proves the critical journey and its first meaningful continuation?" | +| **Single component for a multi-service journey** | "Which required API, worker, store, asset, auth, or external dependency is being skipped?" | +| **Screenshot or HTTP 200 as E2E proof** | "Could this evidence pass while the next user action, API call, or asset still fails?" | ## Reference Loading Guide diff --git a/app-architect-brainstorm/assets/VALIDATION-CHECKLIST.md b/app-architect-brainstorm/assets/VALIDATION-CHECKLIST.md index 9b78b20..7da4f0d 100644 --- a/app-architect-brainstorm/assets/VALIDATION-CHECKLIST.md +++ b/app-architect-brainstorm/assets/VALIDATION-CHECKLIST.md @@ -7,6 +7,25 @@ This checklist prevents the agent from generating "pragmatic" code that bypasses --- +## Section 0: Product Truth Contract + +Before accepting the architecture package, verify that every P0 journey has a +Product Truth Contract containing: + +- an exact product claim, actor, intended starting state, trigger, observable + outcome, and first meaningful continuation; +- the complete required runtime topology, including APIs, workers, stores, + assets, auth, external systems, and configuration where applicable; +- explicit failure signals and forbidden substitutes; +- one planned deterministic E2E proof that can fail on the user's exact symptom; +- a same-scenario parity bar when a reference product is named. + +The architecture package must label this evidence state `architected`. Static +mockups, diagrams, guardian checks, and internal tests must never be described +as `product_verified`. + +--- + ## Section A: Folder Structure Compliance Verify the generated folders match the required architecture exactly: diff --git a/app-architect-brainstorm/assets/templates/arch-spec-template.md b/app-architect-brainstorm/assets/templates/arch-spec-template.md index 60a3c51..b4e4d4a 100644 --- a/app-architect-brainstorm/assets/templates/arch-spec-template.md +++ b/app-architect-brainstorm/assets/templates/arch-spec-template.md @@ -20,6 +20,30 @@ - {Metric 1} - {Metric 2} +## 2.1 Product Truth Contract + +| Field | Decision | +|-------|----------| +| Contract ID | `PTC-001` | +| Product claim | {Exact sentence allowed only when the journey passes} | +| Required proof level | {L4 product outcome / L5 reference parity} | +| Actor and starting state | {Role, repository/data/auth/environment} | +| Trigger | {Exact user action or request} | +| Observable outcome | {Visible or consumer-visible result} | +| Critical continuation | {First meaningful action after initial success} | +| Required topology | {UI, API, workers, stores, assets, auth, external systems} | +| Failure signals | {Conditions that make the gate fail} | +| Forbidden substitutes | {Mocks, manual setup, skipped services, one-off patches} | +| Planned evidence command | {Deterministic E2E test capable of reproducing the failure} | +| Reference and parity bar | {If applicable: identical scenario and allowed differences} | + +### Journey Traceability +| Step | Required component/data | Observable assertion | Failure diagnostic | +|------|-------------------------|----------------------|--------------------| +| {1} | {...} | {...} | {...} | + +**Architecture-phase state:** `architected` — runtime verification belongs to implementation and validation. + ## 3. Domain Model ### Core Entities ```mermaid diff --git a/product-truth-gate/SKILL.md b/product-truth-gate/SKILL.md new file mode 100644 index 0000000..44b78a1 --- /dev/null +++ b/product-truth-gate/SKILL.md @@ -0,0 +1,165 @@ +--- +name: product-truth-gate +description: > + Define and enforce an observable product-outcome contract before declaring a + feature, application, integration, migration, or repair usable or complete. + Use when success depends on a real user journey or several runtime components, + especially for existing repositories, local previews, deployments, imports, + integrations, or comparisons with a reference product. Do not invoke for + documentation-only work or isolated code changes that make no product claim. +--- + +# Product Truth Gate + +Prevent plausible architecture, green internal tests, HTTP success, or a visible +shell from being mistaken for a working product. The gate evaluates the exact +outcome promised to the user, at the boundary where they experience it. + +This skill does not replace architecture, implementation, QA, or security +review. It decides what evidence is allowed to support a product claim. + +## Non-negotiable rule + +Never claim `done`, `fixed`, `usable`, `live`, `ready`, or parity with another +product unless the required Product Truth Contract has passed end to end. + +Lower-level evidence is useful but cannot substitute for higher-level evidence: + +| Level | Evidence | What it proves | +|---|---|---| +| L0 | Architecture, specification, diagrams | The solution is reasoned about | +| L1 | Static checks and unit tests | Isolated rules behave as expected | +| L2 | Component and integration tests | Selected boundaries cooperate | +| L3 | Visible surface or successful response | A screen or endpoint can load | +| L4 | Critical user journey with its required runtime topology | The promised outcome works | +| L5 | Same-scenario comparison against a named reference | The stated parity claim is supported | + +If the user's claim requires L4, L0-L3 remain `implemented_unverified` or +`partially_working`. A screenshot, `200`, health check, process PID, `live` +badge, or green unit suite is never L4 by itself. + +## 1. Write the Product Truth Contract first + +Before implementation or diagnosis, make the contract explicit. For an +architecture-only task, include it in the architecture package as a future +implementation gate; do not pretend to execute it. + +Capture: + +- **Actor and starting state**: who starts where, with what repository/data/auth. +- **Trigger**: the exact action the actor performs. +- **Observable outcome**: what must be visible or possible afterward. +- **Critical continuation**: the first meaningful action after initial render. +- **Required topology**: frontend, APIs, workers, databases, object stores, + queues, third-party services, assets, auth, configuration, and ports that the + journey actually needs. +- **Failure signals**: messages, blank assets, failed requests, broken reloads, + missing data, dead controls, or degraded behavior that make the gate red. +- **Forbidden substitutes**: mocks, synthetic data, manual database edits, + one-off commands, hidden configuration, skipped services, or product-specific + patches that the intended workflow would not perform. +- **Evidence command**: one deterministic, agent-runnable test that can go red + on the exact user-visible failure. +- **Reference scenario**: when parity is claimed, the identical input and + journey to run on both products. + +Use [references/truth-contract-template.md](references/truth-contract-template.md) +when producing or auditing a formal contract. + +If a material field is unknown, ask or discover it. Do not silently weaken the +claim to match what is easy to test. + +## 2. Reconstruct the real runtime topology + +For an existing repository, derive topology from the repository and runtime, +not from the most convenient package: + +1. Inspect root scripts, workspace manifests, compose files, environment + schemas, service entry points, asset paths, API base URLs, workers, migrations, + and readiness dependencies. +2. Map each step of the critical journey to the process and data it needs. +3. Mark services as required, optional, or external, with evidence. +4. Challenge any plan that starts only one component of a multi-service journey. + +Starting the frontend alone is valid only when the contract explicitly asks for +a frontend-only artifact. Otherwise it is partial evidence, not product success. + +## 3. Build a red-capable truth loop + +Create the smallest deterministic loop that exercises the real boundary: + +- Prefer a browser or API E2E that performs the user's action and asserts both + the visible result and the critical continuation. +- Verify resource loading, API calls, authentication, persistence/reload, and + required background work when they are part of the contract. +- Run it before the fix and record the red symptom. +- Keep it runnable without human interpretation. A human screenshot review may + supplement the loop, but must not be its only assertion. + +If the environment prevents the loop from running, report `blocked_unverified`. +Do not implement around the missing proof and later call the outcome complete. + +## 4. Implement against the contract + +Use lower-level tests to localize failures, but repeatedly return to the truth +loop. Every workaround must answer: + +- Would a fresh user or fresh checkout receive this automatically? +- Does it preserve the intended security and architecture boundaries? +- Does it work after restart and reload? +- Does it support the next meaningful action, not just the first paint? +- Is this general behavior or an undeclared product-specific exception? + +Manual state mutation may be useful for diagnosis. It is never completion +evidence unless manual operation is explicitly part of the product contract. + +## 5. Run the adversarial completion review + +Before reporting success, actively try to falsify it: + +- Start from the user's actual initial state or a clean equivalent. +- Run the exact truth loop again. +- Inspect failed network requests and missing assets, not only DOM presence. +- Exercise the first meaningful control after load. +- Reload or restart when persistence/runtime recovery is part of normal use. +- For parity, run the same scenario against the reference and record meaningful + differences rather than comparing feature lists. + +Produce a claim-to-evidence table: + +| Claim | Required level | Evidence | Result | +|---|---:|---|---| +| ... | L4 | exact command/artifact | pass/fail/blocked | + +One failed required claim makes the product gate fail. + +## 6. Use honest completion states + +Report exactly one state: + +- `architected`: specification exists; runtime outcome not implemented. +- `implemented_unverified`: code exists; truth loop did not run. +- `partially_working`: some required claims pass and at least one fails. +- `blocked_unverified`: the required proof cannot run in the current environment. +- `product_verified`: every required claim passes from the intended starting state. +- `parity_verified`: L5 same-scenario comparison passes the declared parity bar. + +Lead with failed or blocked product claims even when internal checks are green. +Do not average architecture quality and runtime failure into a positive verdict. + +## Pairing with app-architect-brainstorm + +The pairing is deliberately asymmetric: + +- `app-architect-brainstorm` discovers and writes the Product Truth Contract as + part of the architecture package. +- `product-truth-gate` consumes that contract during implementation, repair, + validation, and parity assessment. +- The architecture phase may declare `architected`, never `product_verified`. +- If implementation reveals missing topology or an invalid assumption, update + the architecture contract rather than weakening the product truth gate. + +The Product Truth Contract should influence component boundaries, local +developer experience, orchestration, observability, acceptance tests, and the +guardian checklist. It must remain outcome-focused rather than prescribing an +implementation prematurely. diff --git a/product-truth-gate/agents/openai.yaml b/product-truth-gate/agents/openai.yaml new file mode 100644 index 0000000..43d2cee --- /dev/null +++ b/product-truth-gate/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Product Truth Gate" + short_description: "Prove real product outcomes before declaring done" + default_prompt: "Use $product-truth-gate to define and verify the real user outcome before declaring this work complete." diff --git a/product-truth-gate/references/truth-contract-template.md b/product-truth-gate/references/truth-contract-template.md new file mode 100644 index 0000000..258b8b6 --- /dev/null +++ b/product-truth-gate/references/truth-contract-template.md @@ -0,0 +1,55 @@ +# Product Truth Contract Template + +Use this template when the work makes a user-visible completion, usability, or +parity claim. Keep one contract per critical journey. + +## Contract + +| Field | Decision | +|---|---| +| Contract ID | `PTC-xxx` | +| Product claim | The exact sentence that may be said only if this gate passes | +| Required proof level | L4 product outcome or L5 parity | +| Actor | User/role/machine performing the journey | +| Starting state | Repository, data, auth, environment, and prior configuration | +| Trigger | Exact action or request | +| Observable outcome | User-visible or consumer-visible result | +| Critical continuation | First meaningful action after initial success | +| Required topology | Processes, stores, workers, external systems, assets, auth | +| Failure signals | Exact conditions that fail the gate | +| Forbidden substitutes | Mocks, manual steps, hidden setup, skipped dependencies | +| Evidence command | Deterministic command or test path | +| Evidence artifacts | Screenshot, trace, logs, hashes, report, or recording | +| Reference product | Required only for parity claims | +| Parity bar | Material behaviors that must match; allowed differences | + +## Journey traceability + +| Journey step | Required component/data | Observable assertion | Failure diagnostic | +|---|---|---|---| +| 1. ... | ... | ... | ... | + +## Acceptance report + +| Claim | Required level | Evidence | Result | +|---|---:|---|---| +| ... | L4 | `command`, artifact path, or trace ID | pass/fail/blocked | + +Final state: `architected | implemented_unverified | partially_working | blocked_unverified | product_verified | parity_verified` + +## Architecture-package use + +During architecture work, fill the contract and map every required topology +item to a component, interface, operational responsibility, and planned E2E +proof. Mark the final state `architected`. Execution belongs to implementation +and validation work. + +## Fast falsification questions + +- Does this still work from a fresh checkout or intended first-run state? +- What happens after the first screen or successful response? +- Which backend, worker, store, or external service makes that action real? +- Do absolute asset and API paths resolve through the intended runtime boundary? +- Does reload/restart preserve the journey when users reasonably expect it? +- Which manual step would a real user not know to perform? +- Could the same evidence pass while the user's actual goal still fails?