docs: streamline solo design workflow

.github/pull_request_template.md

@@ -1,3 +1,7 @@
+## Problem, rationale, and scope
+
+<!-- State the Mango user/operator problem, acceptance criteria, and non-goals. An Issue is optional. -->
+
 ## What changed
 
 <!-- Describe the problem and the smallest useful solution. -->
@@ -8,14 +12,15 @@
 
 ## API impact and design provenance
 
-<!-- Describe public API impact. Link material design sources and record what Mango adopted, changed, or rejected and why. -->
+<!-- Describe public API impact. For analogous CMA or external designs, record what Mango adopted, adapted, or rejected and why. Explain any new Mango-specific concept instead of inventing one silently. -->
 
 ## Durability and security
 
 <!-- Note migration, retry, side-effect, credential, tool, and sandbox impact. -->
 
 ## Checklist
 
+- [ ] The problem, acceptance criteria, and non-goals are recorded here or in a linked design document/Issue.
 - [ ] Tests cover the changed behavior.
 - [ ] Public behavior is documented.
 - [ ] Material external design influences and Mango-owned decisions are recorded.

AGENTS.md

@@ -42,6 +42,10 @@ pull-request requirements.
   evolution deliberately: understand what problem a change solves and what was
   learned from it. This is a research obligation, not a compatibility
   obligation.
+- The normal design workflow starts from Mango's current source, migrations,
+  OpenAPI, documentation, and executable tests, then compares the analogous
+  current CMA workflow. Differences are useful design evidence, not an
+  automatic parity backlog and not a reason to preserve stale Mango behavior.
 - Before finalizing substantial Mango work that has an analogous CMA workflow,
   review the current relevant CMA design alongside Mango's implementation and
   other useful references. Do not wait for CMA, and do not create work merely
@@ -54,6 +58,15 @@ pull-request requirements.
   JSON fields, event types, and public SDK types may be design starting points
   when they reduce unnecessary invention and fit Mango's workflows. Mango does
   not need to rename or reshape a sound concept merely to appear different.
+- When Mango and CMA solve the same user problem with the same lifecycle,
+  prefer the same sound high-level design over gratuitous divergence. Exact
+  field-for-field equality is not a goal: omit hosted rollout details and
+  fields Mango does not need, and change a field when Mango's self-hosted
+  semantics require it.
+- Prefer standard HTTP semantics, widely understood data shapes, and existing
+  Mango resource and event primitives. Introduce a Mango-specific header,
+  wrapper, field, state, or abstraction only when a concrete requirement cannot
+  be expressed clearly with an established convention or existing primitive.
 - Once adopted, the resulting surface is owned by Mango. Similarity to CMA does
   not create compatibility, synchronization, migration, or release-timing
   obligations. Mango may change, remove, or extend that design directly on
@@ -66,16 +79,19 @@ pull-request requirements.
 - For every material influence, record what Mango adopted, changed, or rejected
   and why in `docs/provenance.md` or the relevant design document. A CMA change
   can trigger design review, but it becomes implementation work only after a
-  Mango user or operator rationale and acceptance criteria exist.
+  Mango user or operator rationale and acceptance criteria exist in the pull
+  request, a design document, or an Issue.
 - Validate the result through Mango's own HTTP, persistence, workflow, recovery,
   and service tests. Passing a third-party SDK test is optional research
   evidence, never the definition of success.
 
 ## Product-driven development
 
 - Mango's documented HTTP API and observable runtime behavior define the
-  product contract. GitHub Issues define active engineering work and may form a
-  Mango-specific roadmap.
+  product contract. GitHub Issues are optional coordination and roadmap tools,
+  not a prerequisite for implementation. For a solo, short-lived change, the
+  pull request may carry the problem statement, rationale, acceptance criteria,
+  and non-goals directly.
 - `docs/product.md` defines product direction. `docs/capabilities.md` records
   Mango's current capabilities and limitations; it is not a delta ledger
   against another service.
@@ -96,9 +112,10 @@ pull-request requirements.
   models, routes, schemas, workflows, or edge cases. Record useful provenance,
   but make the resulting contract Mango's own, adapt it to the self-hosted trust
   boundary, and reject constraints that do not serve Mango users.
-- Do not add research-preview or vendor-specific surfaces unless a Mango issue
-  explicitly selects them for an independent product reason.
-- Stop when the acceptance criteria and required tests pass. Record adjacent
-  work as separate Issues instead of expanding the current change.
+- Do not add research-preview or vendor-specific surfaces unless the change
+  explicitly selects them for an independent Mango product reason.
+- Stop when the acceptance criteria and required tests pass. Keep adjacent work
+  out of the current slice; record it in a follow-up PR, design note, or Issue
+  when coordination or longer-term tracking is useful.
 - A completed user-visible change must update the affected API documentation,
   `internal/httpapi/openapi.yaml`, and the capability summary when applicable.

CONTRIBUTING.md

@@ -8,17 +8,21 @@ design starting points when they fit Mango and avoid unnecessary invention.
 Changes must still preserve a clear line between external design research and
 Mango's original implementation and product decisions.
 
-## Before opening a change
+## Before a substantial change
 
-For substantial API, persistence, or runtime changes, open an issue describing:
+Describe the following in the pull request, a design document, or an Issue:
 
 - the user-visible problem;
 - the Mango user or operator rationale and any relevant design references;
 - the durability, retry, and security implications;
 - a small independently testable delivery slice.
 
-Small bug fixes and documentation improvements can go directly to a pull
-request.
+Issues are optional coordination and roadmap tools, not an implementation gate.
+For solo development and short-lived work, putting this context directly in the
+pull request is preferred over opening an Issue that will immediately close.
+Use an Issue when work benefits from discussion, sequencing, ownership, or
+longer-term tracking. Small bug fixes and documentation improvements can go
+directly to a pull request with proportionate context.
 
 ## Development setup
 
@@ -114,11 +118,19 @@ influences and the adopted, changed, or rejected decisions in
 implementation code or non-public types. An existing third-party client test
 is optional research evidence, not by itself a reason to preserve an API shape.
 
+When the user problem and lifecycle match, prefer an established CMA design or
+another widely used convention over inventing a Mango-only equivalent. Exact
+field parity is not required: keep the fields Mango needs, reject hosted or
+rollout-only details, and adapt semantics to self-hosting. Prefer standard HTTP,
+simple general data shapes, and existing Mango primitives before introducing a
+new header, wrapper, state, field, or abstraction.
+
 ## Sandbox backend changes
 
-Open an issue before adding a substantial sandbox backend. Describe the target
-use case, trust boundary, host dependencies, network defaults, resource
-controls, session persistence, and restart behavior.
+Before adding a substantial sandbox backend, describe the target use case,
+trust boundary, host dependencies, network defaults, resource controls, session
+persistence, and restart behavior in the pull request, a design document, or an
+Issue.
 
 Backend changes should preserve the provider contract and session-scoped
 ownership described in the [sandbox backend guide](docs/sandboxes.md). Keep

README.md

@@ -108,8 +108,9 @@ make local-down
 The [capability summary](https://yanpgwang.github.io/mango/capabilities)
 states the user-visible boundary. Persistent child-Agent orchestration,
 provider-neutral Advisor consultations, and shared Session budgets are
-implemented; active product work belongs in focused
-[GitHub Issues](https://github.com/yanpgwang/mango/issues).
+implemented. Active product work may live directly in focused pull requests;
+[GitHub Issues](https://github.com/yanpgwang/mango/issues) are used when
+discussion, sequencing, or longer-term tracking is useful.
 
 ## Architecture
 

docs/architecture.md

@@ -208,5 +208,6 @@ The strongest current risks are semantic rather than structural:
    child before primary Workflow and sandbox cleanup.
 
 Current API support is tracked in [capabilities and limits](capabilities.md).
-[Product direction](product.md) defines how Mango selects work, and focused
-engineering belongs in [GitHub Issues](https://github.com/yanpgwang/mango/issues).
+[Product direction](product.md) defines how Mango selects work. Focused changes
+may be tracked directly in pull requests; Issues remain available when work
+needs discussion, sequencing, or longer-term coordination.

docs/capabilities.md

@@ -81,5 +81,6 @@ PostgreSQL/Temporal/NATS/MinIO/Docker service tests.
 Mango has not published a versioned release. Published versions will appear in
 [GitHub Releases](https://github.com/yanpgwang/mango/releases). Follow Mango's
 [API reference](api/overview.md) for the current wire surface, this page for
-operational boundaries, and [GitHub Issues](https://github.com/yanpgwang/mango/issues)
-for active work.
+operational boundaries, and current
+[pull requests](https://github.com/yanpgwang/mango/pulls) or optional
+[Issues](https://github.com/yanpgwang/mango/issues) for active work.

docs/product.md

@@ -81,7 +81,11 @@ not automatically permanent. During the transition:
   Mango currently does;
 - [API reference](api/overview.md) and the served OpenAPI document define the
   current HTTP surface;
-- [GitHub Issues](https://github.com/yanpgwang/mango/issues) hold active Mango
-  engineering work;
-- differences from external contracts are not backlog items unless an Issue
-  gives them a Mango-specific rationale.
+- current source, migrations, documentation, and executable tests are the
+  starting point for implementation decisions;
+- [GitHub pull requests](https://github.com/yanpgwang/mango/pulls), design
+  documents, and optional [Issues](https://github.com/yanpgwang/mango/issues)
+  may carry active work and rationale;
+- differences from external contracts are design inputs, not backlog items,
+  unless a Mango change gives them a user or operator rationale and acceptance
+  criteria.

docs/sandboxes.md

@@ -270,5 +270,6 @@ A backend contribution should:
 - avoid a production or multi-tenant safety claim without evidence and an
   explicit security review.
 
-Open an issue before a substantial backend integration so the intended use case
-and lifecycle implications can be reviewed independently of the adapter code.
+Before a substantial backend integration, record the intended use case and
+lifecycle implications in the pull request, a design document, or an Issue so
+they can be reviewed independently of the adapter code.