docs: Import common best practices from catalogue

docs/project-specification/05-authoring-best-practices.md

@@ -0,0 +1,19 @@
+# Project Authoring Best Practices
+
+Recommendations for delivering the best and most consistent user experience with Topo Projects
+
+## Be semantically correct and leverage `x-topo` attributes as appropriate
+
+`x-topo` contains attributes that help users discover and use your Project. Ensure you have considered all available attributes in the schema and used them as appropriate.
+
+The [Project-authoring skills](https://github.com/arm/topo#project-authoring-skills) can help you lint and improve your Project.
+
+## Only require `topo deploy` to build and run
+
+Running `topo deploy` should be sufficient to build and start the application. Define every required build, dependency-fetching, and setup step in `compose.yaml` or its Dockerfiles, or provide the result in a referenced container image. Do not require users to run additional commands manually.
+
+[Multi-stage builds](https://docs.docker.com/build/building/multi-stage/) can be used for compilation, dependency fetching, code generation, and asset bundling. Copy only the resulting artifacts and runtime dependencies into the final stage. This ensures `topo deploy` performs the complete build while keeping build tools, caches, and other build-only files out of the runtime image.
+
+### Be fast to build and iterate
+
+The best Projects are fast to build, deploy, and iterate on. See [Build Optimization](04-build-optimization.md) or use the [`topo-project-optimize-deployment` skill](https://github.com/arm/topo#project-authoring-skills) for guidance on specific performance best practices.

docs/project-specification/README.md

@@ -42,6 +42,8 @@ Because this is valid Compose, any Project can be run with plain `docker compose
   - [Authoring Topo Projects](01-authoring-projects.md)
   - [Project Configuration](02-project-configuration.md)
   - [Schema Compliance](03-schema.md)
+  - [Build Optimization](04-build-optimization.md)
+  - [Authoring Best Practices](05-authoring-best-practices.md)
 - Machine-readable schema:
   - [`schema/topo-project-specification.json`](https://github.com/arm/topo/blob/main/docs/project-specification/schema/topo-project-specification.json)
 
@@ -58,9 +60,10 @@ We welcome any contributors who wish to add their own Project to the project cat
 
 If you want your Project to be added to the project catalog:
 
-1. Review the [Authoring Topo Projects section of the Specification](01-authoring-projects.md).
-2. [Validate Schema Compliance](#validate-schema-compliance) of your proposed Project.
-3. Open a Pull Request in the `Topo Project Catalog` repository to update the [catalog sources](https://github.com/arm/topo-project-catalog/blob/main/data/github_sources.json).
+1. Review the [Authoring Best Practices](05-authoring-best-practices.md).
+2. Review the catalog's [Project Acceptance Criteria](https://github.com/arm/topo-project-catalog/blob/main/docs/project-acceptance-criteria.md).
+3. [Validate Schema Compliance](#validate-schema-compliance) of your proposed Project.
+4. Open a Pull Request in the `Topo Project Catalog` repository to update the [catalog sources](https://github.com/arm/topo-project-catalog/blob/main/data/github_sources.json).
 
 ### Validate Schema Compliance
 

skills/_shared/topo-project-context.md

@@ -15,10 +15,13 @@ Use Topo vocabulary precisely:
 Refresh spec-sensitive context at runtime before making or validating Project changes. Authoritative references, in order:
 
 - Published Topo Project Specification schema: `https://raw.githubusercontent.com/arm/topo/refs/heads/main/docs/project-specification/schema/topo-project-specification.json`.
-- Published Topo Project Specification docs: `https://github.com/arm/topo/tree/main/docs/project-specification`, especially `README.md`, `01-authoring-projects.md`, `02-project-configuration.md`, and `03-schema.md`.
+- Published Topo Project Specification docs: `https://github.com/arm/topo/tree/main/docs/project-specification`, especially `README.md`, `01-authoring-projects.md`, `02-project-configuration.md`, `03-schema.md`, and `05-authoring-best-practices.md`.
+- Topo Project Catalog acceptance policy: `https://github.com/arm/topo-project-catalog/blob/main/docs/project-acceptance-criteria.md`.
 - Published Topo glossary for domain terms: `https://github.com/arm/topo/blob/main/docs/introduction/glossary.md`.
 - Compose Spec for standard Compose semantics. Do not invent non-standard Compose keys except the root-level `x-topo` extension.
 
 When references conflict, prefer the schema for validation behavior, then the specification docs for authoring intent, then the target repository's actual Compose behavior for the smallest safe change.
 
+Keep specification requirements, authoring best practices, and catalog policy distinct. The schema and specification define whether a Project is valid. The authoring best practices provide technical guidance for making Projects accurate, reproducible, adaptable, tested, and fast to iterate. The catalog applies additional curation and acceptance policy. Only apply catalog policy when the user asks about catalog inclusion, submission, acceptance, or readiness.
+
 When validating changes, check if `topo` is installed, and prompt the user for an SSH target to test against. `topo clone dir:./path/to/project` can be used to test project parameters, `topo deploy` can be used to test build and deploy.

skills/topo-project-bootstrap/references/topo-project-context.md

@@ -15,10 +15,13 @@ Use Topo vocabulary precisely:
 Refresh spec-sensitive context at runtime before making or validating Project changes. Authoritative references, in order:
 
 - Published Topo Project Specification schema: `https://raw.githubusercontent.com/arm/topo/refs/heads/main/docs/project-specification/schema/topo-project-specification.json`.
-- Published Topo Project Specification docs: `https://github.com/arm/topo/tree/main/docs/project-specification`, especially `README.md`, `01-authoring-projects.md`, `02-project-configuration.md`, and `03-schema.md`.
+- Published Topo Project Specification docs: `https://github.com/arm/topo/tree/main/docs/project-specification`, especially `README.md`, `01-authoring-projects.md`, `02-project-configuration.md`, `03-schema.md`, and `05-authoring-best-practices.md`.
+- Topo Project Catalog acceptance policy: `https://github.com/arm/topo-project-catalog/blob/main/docs/project-acceptance-criteria.md`.
 - Published Topo glossary for domain terms: `https://github.com/arm/topo/blob/main/docs/introduction/glossary.md`.
 - Compose Spec for standard Compose semantics. Do not invent non-standard Compose keys except the root-level `x-topo` extension.
 
 When references conflict, prefer the schema for validation behavior, then the specification docs for authoring intent, then the target repository's actual Compose behavior for the smallest safe change.
 
+Keep specification requirements, authoring best practices, and catalog policy distinct. The schema and specification define whether a Project is valid. The authoring best practices provide technical guidance for making Projects accurate, reproducible, adaptable, tested, and fast to iterate. The catalog applies additional curation and acceptance policy. Only apply catalog policy when the user asks about catalog inclusion, submission, acceptance, or readiness.
+
 When validating changes, check if `topo` is installed, and prompt the user for an SSH target to test against. `topo clone dir:./path/to/project` can be used to test project parameters, `topo deploy` can be used to test build and deploy.

skills/topo-project-context/references/topo-project-context.md

@@ -15,10 +15,13 @@ Use Topo vocabulary precisely:
 Refresh spec-sensitive context at runtime before making or validating Project changes. Authoritative references, in order:
 
 - Published Topo Project Specification schema: `https://raw.githubusercontent.com/arm/topo/refs/heads/main/docs/project-specification/schema/topo-project-specification.json`.
-- Published Topo Project Specification docs: `https://github.com/arm/topo/tree/main/docs/project-specification`, especially `README.md`, `01-authoring-projects.md`, `02-project-configuration.md`, and `03-schema.md`.
+- Published Topo Project Specification docs: `https://github.com/arm/topo/tree/main/docs/project-specification`, especially `README.md`, `01-authoring-projects.md`, `02-project-configuration.md`, `03-schema.md`, and `05-authoring-best-practices.md`.
+- Topo Project Catalog acceptance policy: `https://github.com/arm/topo-project-catalog/blob/main/docs/project-acceptance-criteria.md`.
 - Published Topo glossary for domain terms: `https://github.com/arm/topo/blob/main/docs/introduction/glossary.md`.
 - Compose Spec for standard Compose semantics. Do not invent non-standard Compose keys except the root-level `x-topo` extension.
 
 When references conflict, prefer the schema for validation behavior, then the specification docs for authoring intent, then the target repository's actual Compose behavior for the smallest safe change.
 
+Keep specification requirements, authoring best practices, and catalog policy distinct. The schema and specification define whether a Project is valid. The authoring best practices provide technical guidance for making Projects accurate, reproducible, adaptable, tested, and fast to iterate. The catalog applies additional curation and acceptance policy. Only apply catalog policy when the user asks about catalog inclusion, submission, acceptance, or readiness.
+
 When validating changes, check if `topo` is installed, and prompt the user for an SSH target to test against. `topo clone dir:./path/to/project` can be used to test project parameters, `topo deploy` can be used to test build and deploy.

skills/topo-project-lint/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: topo-project-lint
-description: Check Topo Project metadata correctness. Use when validating compose.yaml x-topo metadata, README alignment, deployment success messages, or project parameter wiring.
+description: Check Topo Project correctness and catalog readiness. Use when validating compose.yaml x-topo metadata, README alignment, deployment success messages, project parameter wiring, or catalog acceptance criteria.
 ---
 
 # Topo Project Lint
 
-Use this skill when the user asks to lint, validate, check, review, or fix Topo Project metadata correctness.
+Use this skill when the user asks to lint, validate, check, review, or fix Topo Project metadata correctness or catalog readiness.
 
 Before acting, read `references/topo-project-context.md` for shared Topo Project vocabulary, authoritative references, and validation expectations.
 
@@ -18,6 +18,7 @@ Run these checks in order. If the user asked you to fix issues, make the smalles
 3. Check that `x-topo.name` and `x-topo.description` match `README.md`.
 4. Check that `x-topo.deployment_success_message` exists and is useful.
 5. Check that every `x-topo.parameters` entry is consumed by the corresponding Docker build.
+6. If catalog readiness was requested, assess the Project against the catalog's current Project Acceptance Criteria.
 
 ## Checks
 
@@ -61,6 +62,14 @@ Run these checks in order. If the user asked you to fix issues, make the smalles
 - Flag `services.<service>.build.args` entries that look user-configurable but are missing from `x-topo.parameters` when the user asked for a comprehensive lint.
 - Do not require runtime-only environment variables to appear in `x-topo.parameters`; this check is only for Docker build arguments.
 
+### 6. Catalog Readiness
+
+- Run this check only when the user asks about catalog inclusion, acceptance, submission, or readiness.
+- Read the current catalog acceptance policy from `https://github.com/arm/topo-project-catalog/blob/main/docs/project-acceptance-criteria.md` before assessing the Project. Do not substitute Topo's authoring best practices for catalog policy.
+- Apply the technical guidance from Topo's authoring best practices first, then assess the additional selection and quality thresholds defined by the catalog.
+- Distinguish repository evidence from checks that were actually run. Do not infer reliability, target compatibility, or performance from metadata alone.
+- Treat schema failures, inaccurate compatibility declarations, and required manual pre-deployment steps as blocking. Report subjective acceptance decisions and tests requiring unavailable target hardware as needing maintainer or hardware validation.
+
 ## Reporting
 
-Report findings in the same order as the checks. Include file paths, line numbers when available, the validation command used, and whether each check passed or failed. If changes were made, summarize the files edited and the re-validation result.
+Report findings in the same order as the checks. Include file paths, line numbers when available, the validation command used, and whether each check passed or failed. For catalog-readiness reviews, separate confirmed evidence, blocking issues, and unverified criteria. If changes were made, summarize the files edited and the re-validation result.

skills/topo-project-lint/references/topo-project-context.md

@@ -15,10 +15,13 @@ Use Topo vocabulary precisely:
 Refresh spec-sensitive context at runtime before making or validating Project changes. Authoritative references, in order:
 
 - Published Topo Project Specification schema: `https://raw.githubusercontent.com/arm/topo/refs/heads/main/docs/project-specification/schema/topo-project-specification.json`.
-- Published Topo Project Specification docs: `https://github.com/arm/topo/tree/main/docs/project-specification`, especially `README.md`, `01-authoring-projects.md`, `02-project-configuration.md`, and `03-schema.md`.
+- Published Topo Project Specification docs: `https://github.com/arm/topo/tree/main/docs/project-specification`, especially `README.md`, `01-authoring-projects.md`, `02-project-configuration.md`, `03-schema.md`, and `05-authoring-best-practices.md`.
+- Topo Project Catalog acceptance policy: `https://github.com/arm/topo-project-catalog/blob/main/docs/project-acceptance-criteria.md`.
 - Published Topo glossary for domain terms: `https://github.com/arm/topo/blob/main/docs/introduction/glossary.md`.
 - Compose Spec for standard Compose semantics. Do not invent non-standard Compose keys except the root-level `x-topo` extension.
 
 When references conflict, prefer the schema for validation behavior, then the specification docs for authoring intent, then the target repository's actual Compose behavior for the smallest safe change.
 
+Keep specification requirements, authoring best practices, and catalog policy distinct. The schema and specification define whether a Project is valid. The authoring best practices provide technical guidance for making Projects accurate, reproducible, adaptable, tested, and fast to iterate. The catalog applies additional curation and acceptance policy. Only apply catalog policy when the user asks about catalog inclusion, submission, acceptance, or readiness.
+
 When validating changes, check if `topo` is installed, and prompt the user for an SSH target to test against. `topo clone dir:./path/to/project` can be used to test project parameters, `topo deploy` can be used to test build and deploy.

skills/topo-project-optimize-deployment/references/topo-project-context.md

@@ -15,10 +15,13 @@ Use Topo vocabulary precisely:
 Refresh spec-sensitive context at runtime before making or validating Project changes. Authoritative references, in order:
 
 - Published Topo Project Specification schema: `https://raw.githubusercontent.com/arm/topo/refs/heads/main/docs/project-specification/schema/topo-project-specification.json`.
-- Published Topo Project Specification docs: `https://github.com/arm/topo/tree/main/docs/project-specification`, especially `README.md`, `01-authoring-projects.md`, `02-project-configuration.md`, and `03-schema.md`.
+- Published Topo Project Specification docs: `https://github.com/arm/topo/tree/main/docs/project-specification`, especially `README.md`, `01-authoring-projects.md`, `02-project-configuration.md`, `03-schema.md`, and `05-authoring-best-practices.md`.
+- Topo Project Catalog acceptance policy: `https://github.com/arm/topo-project-catalog/blob/main/docs/project-acceptance-criteria.md`.
 - Published Topo glossary for domain terms: `https://github.com/arm/topo/blob/main/docs/introduction/glossary.md`.
 - Compose Spec for standard Compose semantics. Do not invent non-standard Compose keys except the root-level `x-topo` extension.
 
 When references conflict, prefer the schema for validation behavior, then the specification docs for authoring intent, then the target repository's actual Compose behavior for the smallest safe change.
 
+Keep specification requirements, authoring best practices, and catalog policy distinct. The schema and specification define whether a Project is valid. The authoring best practices provide technical guidance for making Projects accurate, reproducible, adaptable, tested, and fast to iterate. The catalog applies additional curation and acceptance policy. Only apply catalog policy when the user asks about catalog inclusion, submission, acceptance, or readiness.
+
 When validating changes, check if `topo` is installed, and prompt the user for an SSH target to test against. `topo clone dir:./path/to/project` can be used to test project parameters, `topo deploy` can be used to test build and deploy.