[Documentation]: Redesign README for Agent-first AutoGenesis 1.1 onboarding

Problem

The repository root README is still the upstream template and presents internal subprojects instead of the released AutoGenesis 1.1 user workflow. A new user or Coding Agent cannot determine the supported hosts, choose the Agent-first or CLI-first installation path, or reach a first real test without navigating several legacy documents.

User outcome

A user can open the root README, choose Agent-first or CLI-first installation, install AutoGenesis without cloning the repository, and give one concrete test request to a supported Coding Agent. The README accurately states supported hosts, platforms, approval boundaries, readiness evidence, and links to deeper platform and contributor documentation.

Scope

Replace the root README template with a concise product README for AutoGenesis 1.1.
Lead with the Agent-first workflow and one copyable install prompt.
Document the CLI-first workflow using the published autogenesis command.
List supported Coding Agents: OMP, Codex CLI, Pi, and GitHub Copilot CLI.
State native macOS and native Windows host support; Linux and WSL are unsupported.
Explain the Setup and Run Skill roles without exposing repository implementation details.
Provide direct-prompt and BDD-recording examples.
Preserve links for platform details, contribution, security, code of conduct, and license.
Keep installation commands aligned with package entrypoints and generated release assets.

Non-goals

No Runtime, Skill, CLI, package, workflow, or schema changes.
No claim that the four Coding Agents or native Windows have completed final compatibility acceptance.
No replacement of platform-specific reference documents.
No release or package publication.

Interfaces affected

The repository landing page and its copyable Agent Install Prompt. Runtime and package interfaces are unchanged.

Acceptance scenarios

Scenario: Agent-first first run
  Given a user has a supported native host, Python 3.10+, and one listed Coding Agent
  When the user follows only the root README Agent-first path
  Then the user can install and discover autogenesis-setup without cloning the repository
  And the agent is instructed to request approval before writes or process execution
  And the README provides a concrete first test request

Scenario: CLI-first first run
  Given a user prefers a terminal installation
  When the user follows only the root README CLI-first path
  Then the documented command installs the host-supported Runtime and both canonical Skills
  And the README explains how the Coding Agent discovers and uses them

Scenario: Honest support status
  Given a reader evaluates compatibility
  When the reader reads the support matrix and limitations
  Then native macOS and native Windows are distinguished from target platforms
  And pending Coding Agent and Windows acceptance is not presented as completed
  And Linux and WSL are explicitly rejected

Verification environments

Rendered GitHub Markdown.
Link and repository-path validation.
User acceptance through the four Coding Agents is performed by the Human Product Owner.

Security considerations

The README contains package-install commands and an Agent prompt that can cause downloads, process execution, and configuration writes. Independent security review is required.

Definition of Ready

User outcome is explicit.
Scope and non-goals are explicit.
Public command names are already defined by the merged AutoGenesis 1.1 release contract.
Acceptance scenarios are observable.
Human Product Owner will perform Coding Agent acceptance.

README redesign evidence for commit ce18d59 / PR #29

Independent code review: APPROVE.

Confirmed package names, versions, entrypoints, Skill role split, readiness conditions, status disclosures, links, and exact gated CLI sequence.
Initial findings for Windows status, bootstrap approval, and physical-iPhone readiness were remediated and re-reviewed.

Independent security review: APPROVE.

Agent Install Prompt now requires exact-plan approval before process execution, network access, or filesystem writes, with fresh approval after any change.
It preserves conflicting existing content and fails closed on shadowing, ambiguity, transformed bytes, digest/Contract mismatch, or inability to prove the discovered path and identity.
The unpublished public package coordinate is explicitly prohibited; exact future CLI commands remain inline documentation, not a runnable shell block.

Prompt eval comparison

Harness: same session slow model for baseline and candidate; independent structured grading.
Fixed cases: approval before fetch, conflicting shadow Skill, changed plan, and unprovable discovery resolution.
Baseline (c7ff16e): 3/4.
Candidate (ce18d59): 4/4.
Regressions: 0.
Candidate improvement: an agent unable to prove the resolved Skill path/digest/version stops instead of reporting installation success.
Raw local evidence: /tmp/autogenesis-readme-prompt-eval.json (synthetic paths only; no credentials).

Verification

Agent Contract Skill/release tests: 18 passed.
Generated Agent Install Prompt matches the README block byte-for-byte.
GitHub GFM render completed successfully.
All 11 repository-relative links resolve.
autogenesis --help and autogenesis install --help matched the documented interface in an isolated verifier environment.
git diff --check passed.

Human Product Owner acceptance remains pending through OMP, Codex CLI, Pi, and GitHub Copilot CLI. Public package/release publication and native Windows acceptance remain gated.

Human Product Owner rejected the first README candidate and approved a new product direction.

Core positioning:

Write the behavior. Watch AI record it. Replay without AI.

AutoGenesis lets development and QA teams describe test cases in BDD natural language. A Coding Agent uses MCP to execute the case against the real application and records the observed calls into generated test code. The resulting case can replay without AI. The product supports Windows, macOS, iOS, and Android.

Required README correction:

Lead with the user outcome and complete BDD-to-replay workflow, not packages or governance mechanics.
Show the difference between AI-assisted recording and AI-free replay.
Explain developer, QA, and CI collaboration.
Keep Agent-first setup primary and demote CLI, package versions, trust mechanics, and Runtime details.
Do not route new users through stale clone-based documentation.
Keep release and compatibility status accurate but below the product story.
A real Hero Demo will be designed and added separately; the rest of the README should proceed now without a fake placeholder.

PR #29 remains unaccepted and will be revised in place.

README product redesign update — commit b66da16

The first candidate was rejected by the Human Product Owner. The revised README now leads with the approved product position:

Write the behavior. Watch AI record it. Replay without AI.

Observable changes:

Leads with BDD → exact real-app execution → observed MCP recording → preview approval → Behave replay.
Explains the development/QA/CI collaboration model before installation.
Makes Agent-first onboarding primary; CLI, package, Runtime, and trust mechanics are lower-level content.
Covers Windows, macOS, iOS, and Android without presenting pending acceptance as complete.
Removes the stale repository template and does not route onboarding through the old clone-based documentation site.
Keeps the full verified Agent Install Prompt in a collapsed reference.
Explicitly qualifies model-backed visual assertions: replay does not require the Coding Agent, while recorded visual-model checks retain their configured model dependency.
Describes actual preview bindings and arbitrary-secret detection limitations without overstating protection.
A real Hero Demo remains intentionally deferred by Product Owner decision; no fake placeholder was added.

Independent review:

Product/correctness review ReadmeProductReviewV2: APPROVE.
Security review ReadmeSecurityReviewV2: APPROVE.

Verification:

GitHub GFM and Mermaid rendering succeeded.
Every repository-relative link resolves.
The collapsed Agent Install Prompt matches generated release output byte-for-byte.
git diff --check passed.

PR: #29

FSQ-style README refinement — commit 7860e26

Human Product Owner direction: learn from https://github.com/FSQ-lab/FSQ and leave unavailable media blank until approved assets arrive.

Changes:

Adopted FSQ's product-first hierarchy: centered position, badges and navigation, complete-test position, evidence sequence, then Quick Start.
Moved Agent-first setup immediately after product proof.
Added user-facing "Go further" and contribution sections.
Reserved invisible blank slots for the approved logo, complete-test video, scenario card, execution capture, and replay evidence. No broken links, invented screenshots, or fake placeholders were added.
Preserved AutoGenesis-specific BDD, preview approval, replay/model exception, pre-release, unsupported-host, credential, and trust-boundary contracts.

Verification:

Published branch rendered on GitHub; Mermaid rendered and all four badges loaded.
Every repository-relative link resolves.
Canonical Agent Install Prompt still matches generated release output byte-for-byte.
git diff --check passed.
Independent product review: FSQReadmeProductReview — APPROVE.
Independent security review: FSQReadmeSecurityReview — APPROVE.

PR: #29

AutoGenesis brand logo — commit 07e66a6

Added original responsive light/dark SVG wordmarks and installed them in the README using <picture> color-scheme selection.

Concept:

Three nodes represent readable BDD behavior steps.
Their paths converge into the generated executable test.
The surrounding arrow represents approved replay and the regression loop.
Typography, loop silhouette, and neutral palette relate the mark to the FSQ family without copying FSQ's shield/check symbol.

Verification:

Both SVGs parse as standalone 520×120 assets.
No scripts, external images, links, or embedded raster data.
Published GitHub README selected the dark variant correctly; image loaded with 420×96.9 rendered bounds and useful alt text.
Independent design review AutoGenesisLogoReview: APPROVE; desktop/mobile/260 px legibility and contrast checked.

Remaining media intentionally blank: complete-test video, Scenario editorial card, execution capture, and preview/replay evidence.

Scoped Edge deployment evidence — commit ba850ef

Human Product Owner confirmed the authoritative public figures and scope. README now presents only:

2.30M test steps executed in the reported 30-day period.
3,193 hours saved in the monthly operating period.
4 platforms: Windows, macOS, iOS, and Android.
99.7% pass-rate consistency.

The section explicitly attributes these to application of the approach on the Microsoft Edge browser product line and states that they are observed deployment results, not projected savings or a universal benchmark. Conflicting draft figures and all other internal PDF claims were excluded.

Verification:

Published GitHub README renders the four-column table and Edge results navigation anchor correctly.
Search confirmed no excluded 1.70M / 2,342 / 107 issues / 700+ / 413 PR / pipeline / flakiness claims.
git diff --check passed.
Independent EdgeMetricsReadmeReview: APPROVE against the supplied PDF and Human Product Owner correction.

PR: #29

Edge deployment proof redesign — commit 58eabb4

Replaced the plain metric table with a high-impact production-scale panel:

2.30M and 3,193 are the dominant first-tier results.
4 platforms and 99.7% consistency form a supporting second tier.
Blue/violet/green accents tie the Edge deployment proof to the AutoGenesis visual system.
An original browser/deployment glyph establishes context without copying the trademarked Microsoft Edge product icon.
README retains truthful Microsoft Edge text and the Microsoft trademark notice.

Responsive delivery:

Desktop asset: 1120×480; GitHub rendered at 838×359.
Mobile asset: dedicated stacked 720×950 composition selected below 480 px; GitHub rendered at 324×428 with no overflow.
Both variants contain no scripts, external resources, links, raster data, or event handlers.
Complete metric prose and descriptive alt text remain outside/alongside the graphic.

Independent EdgeImpactPanelReview: initial mobile microcopy blocker fixed; final verdict APPROVE.

PR: #29

README integration update — 090dcb2

Completed:

rebased/integrated current origin/main (7bc9af2);
corrected onboarding for published Contract 2.0.0 / CLI 0.1.0 / Runtime 0.4.0 coordinates;
all package commands retain the machine-configured package index and do not bypass its mirror/trust policy;
removed the link to the older v2.0.0 release prompt; the strengthened inline prompt is the sole Agent-first copy source;
added mandatory post-CLI Skill enumeration, shadow/conflict rejection, and resolved path/bytes/Contract proof;
updated macOS, mobile, and Windows Runtime references so local wheels are maintainer-only;
agent-contract/tests/test_skills.py: 18 passed;
generated prompt matches the inline README block byte-for-byte;
all 11 repository-relative links resolve;
pushed GitHub render verified: logo, Mermaid, Edge panels, navigation, collapsed prompt, configured-index warning, and CLI identity checks are present.

Independent final product/code review: APPROVE.

Independent security review: REQUEST_CHANGES on one release-integrity blocker. The official immutable agent-contract-v2.0.0 release still contains the older prompt bytes, while the branch generator now emits the strengthened prompt under that same release identity. Unlinking and warning in README mitigates the primary path but cannot revoke or reproduce the existing official asset.

Required before merge: publish the strengthened prompt under a new immutable identity (prompt-only version or new Contract release), update README/generator/workflow/tests to that identity, and explicitly mark the old prompt superseded. This is a Human Product Owner release decision; PR #29 remains unmerged.

Navigation Menu

Repository navigation

[Documentation]: Redesign README for Agent-first AutoGenesis 1.1 onboarding #28

Problem

User outcome

Scope

Non-goals

Interfaces affected

Acceptance scenarios

Verification environments

Security considerations

Definition of Ready

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

[Documentation]: Redesign README for Agent-first AutoGenesis 1.1 onboarding #28

Description

Problem

User outcome

Scope

Non-goals

Interfaces affected

Acceptance scenarios

Verification environments

Security considerations

Definition of Ready

Activity

houlianpi commented on Oct 29, 2026

houlianpi commented on Oct 29, 2026

houlianpi commented on Oct 29, 2026

houlianpi commented on Oct 29, 2026

houlianpi commented on Oct 29, 2026

houlianpi commented on Oct 29, 2026

houlianpi commented on Oct 29, 2026

houlianpi commented on Oct 30, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions