From 74a795636a6a576e8e8f7b18b00c9a0efa64a1b7 Mon Sep 17 00:00:00 2001 From: Daniel Blignaut Date: Mon, 7 Sep 2026 16:20:36 +0200 Subject: [PATCH 1/3] docs: standardize repository decisions and change records --- .agents/skills/create-pr/SKILL.md | 28 +++++++++++ .agents/skills/grill-with-docs/ADR-FORMAT.md | 50 ++----------------- .agents/skills/grill-with-docs/SKILL.md | 20 ++++++-- .../improve-codebase-architecture/SKILL.md | 14 +++++- .agents/skills/maintain-docs/SKILL.md | 23 +++++++++ .agents/skills/pre-commit-checks/SKILL.md | 26 ++++++++++ .github/pull_request_template.md | 15 ++++++ .gitmodules | 2 +- AGENTS.md | 13 ++++- Makefile | 4 +- README.md | 8 +++ docs/README.md | 50 +++++++++++++++++++ ...001-repository-documentation-convention.md | 33 ++++++++++++ docs/adrs/README.md | 18 +++++++ docs/adrs/template.md | 23 +++++++++ docs/updates/README.md | 26 ++++++++++ .../pending/documentation-conventions.md | 42 ++++++++++++++++ docs/updates/template.md | 31 ++++++++++++ docs => public-docs | 0 skills/add-provider/SKILL.md | 4 +- skills/update-provider/SKILL.md | 4 +- tools/generatedocs/main.go | 2 +- 22 files changed, 374 insertions(+), 62 deletions(-) create mode 100644 .agents/skills/create-pr/SKILL.md create mode 100644 .agents/skills/maintain-docs/SKILL.md create mode 100644 .agents/skills/pre-commit-checks/SKILL.md create mode 100644 .github/pull_request_template.md create mode 100644 docs/README.md create mode 100644 docs/adrs/0001-repository-documentation-convention.md create mode 100644 docs/adrs/README.md create mode 100644 docs/adrs/template.md create mode 100644 docs/updates/README.md create mode 100644 docs/updates/pending/documentation-conventions.md create mode 100644 docs/updates/template.md rename docs => public-docs (100%) diff --git a/.agents/skills/create-pr/SKILL.md b/.agents/skills/create-pr/SKILL.md new file mode 100644 index 0000000..7d070e3 --- /dev/null +++ b/.agents/skills/create-pr/SKILL.md @@ -0,0 +1,28 @@ +--- +name: create-pr +description: Prepare or update a pull request with focused validation, current ADRs, and a complete PR update record. +--- + +# Create or update a pull request + +## Repository documentation requirements + +Follow [docs/README.md](../../../docs/README.md) for every change in this workflow. Create or update +ADRs for resolved durable decisions, keep affected README/setup/public docs current, +and maintain the complete pending or PR-numbered update record after every revision. +Use the shared templates and section names. Missing or stale required documentation +blocks completion. Document already authorized decisions without asking again; ask +only about unresolved choices. These requirements govern documentation instructions +elsewhere in this skill; preserve its repository-specific implementation and checks. + +Inspect the actual base branch, current diff, existing PR, and unrelated workspace +changes. Complete authorized implementation and focused repository checks before +publishing. Follow `pre-commit-checks` and `maintain-docs`; include affected ADRs, +README/setup/public docs, and the pending update record in the reviewed diff. + +When publishing is authorized, intentionally stage the task files, commit, push, +and open or update a draft PR. Read its actual number/URL, rename the pending record +to `docs/updates/.md`, update its contents, and push it to the same PR. Link +that record and relevant ADRs/related PRs in the description. Recheck the full diff, +validation, and documentation after later review or rebase changes. Never include +unrelated work, secret values, or unverified claims. Do not merge unless authorized. diff --git a/.agents/skills/grill-with-docs/ADR-FORMAT.md b/.agents/skills/grill-with-docs/ADR-FORMAT.md index da7e78e..3836c6b 100644 --- a/.agents/skills/grill-with-docs/ADR-FORMAT.md +++ b/.agents/skills/grill-with-docs/ADR-FORMAT.md @@ -1,47 +1,5 @@ -# ADR Format +# ADR format -ADRs live in `docs/adr/` and use sequential numbering: `0001-slug.md`, `0002-slug.md`, etc. - -Create the `docs/adr/` directory lazily — only when the first ADR is needed. - -## Template - -```md -# {Short title of the decision} - -{1-3 sentences: what's the context, what did we decide, and why.} -``` - -That's it. An ADR can be a single paragraph. The value is in recording *that* a decision was made and *why* — not in filling out sections. - -## Optional sections - -Only include these when they add genuine value. Most ADRs won't need them. - -- **Status** frontmatter (`proposed | accepted | deprecated | superseded by ADR-NNNN`) — useful when decisions are revisited -- **Considered Options** — only when the rejected alternatives are worth remembering -- **Consequences** — only when non-obvious downstream effects need to be called out - -## Numbering - -Scan `docs/adr/` for the highest existing number and increment by one. - -## When to offer an ADR - -All three of these must be true: - -1. **Hard to reverse** — the cost of changing your mind later is meaningful -2. **Surprising without context** — a future reader will look at the code and wonder "why on earth did they do it this way?" -3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons - -If a decision is easy to reverse, skip it — you'll just reverse it. If it's not surprising, nobody will wonder why. If there was no real alternative, there's nothing to record beyond "we did the obvious thing." - -### What qualifies - -- **Architectural shape.** "We're using a monorepo." "The write model is event-sourced, the read model is projected into Postgres." -- **Integration patterns between contexts.** "Ordering and Billing communicate via domain events, not synchronous HTTP." -- **Technology choices that carry lock-in.** Database, message bus, auth provider, deployment target. Not every library — just the ones that would take a quarter to swap out. -- **Boundary and scope decisions.** "Customer data is owned by the Customer context; other contexts reference it by ID only." The explicit no-s are as valuable as the yes-s. -- **Deliberate deviations from the obvious path.** "We're using manual SQL instead of an ORM because X." Anything where a reasonable reader would assume the opposite. These stop the next engineer from "fixing" something that was deliberate. -- **Constraints not visible in the code.** "We can't use AWS because of compliance requirements." "Response times must be under 200ms because of the partner API contract." -- **Rejected alternatives when the rejection is non-obvious.** If you considered GraphQL and picked REST for subtle reasons, record it — otherwise someone will suggest GraphQL again in six months. +Use the shared [ADR convention and template](../../../docs/adrs/README.md). Read the governing +record before changing a decision. Record already resolved decisions directly and +append timestamped amendment history; ask only when the decision is unresolved. diff --git a/.agents/skills/grill-with-docs/SKILL.md b/.agents/skills/grill-with-docs/SKILL.md index 5ea0aa9..70d57b7 100644 --- a/.agents/skills/grill-with-docs/SKILL.md +++ b/.agents/skills/grill-with-docs/SKILL.md @@ -43,13 +43,13 @@ If a `CONTEXT-MAP.md` exists at the root, the repo has multiple contexts. The ma ├── src/ │ ├── ordering/ │ │ ├── CONTEXT.md -│ │ └── docs/adr/ ← context-specific decisions +│ │ └── docs/adrs/ ← context-specific decisions │ └── billing/ │ ├── CONTEXT.md -│ └── docs/adr/ +│ └── docs/adrs/ ``` -Create files lazily — only when you have something to write. If no `CONTEXT.md` exists, create one when the first term is resolved. If no `docs/adr/` exists, create it when the first ADR is needed. +Create files lazily — only when you have something to write. If no `CONTEXT.md` exists, create one when the first term is resolved. If no `docs/adrs/` exists, create it when the first ADR is needed. ## During the session @@ -75,9 +75,9 @@ When a term is resolved, update `CONTEXT.md` right there. Don't batch these up `CONTEXT.md` should be totally devoid of implementation details. Do not treat `CONTEXT.md` as a spec, a scratch pad, or a repository for implementation decisions. It is a glossary and nothing else. -### Offer ADRs sparingly +### Record durable decisions -Only offer to create an ADR when all three are true: +Create or update an ADR when a resolved decision carries durable reasoning. Strong signals include: 1. **Hard to reverse** — the cost of changing your mind later is meaningful 2. **Surprising without context** — a future reader will wonder "why did they do it this way?" @@ -86,3 +86,13 @@ Only offer to create an ADR when all three are true: If any of the three is missing, skip the ADR. Use the format in [ADR-FORMAT.md](./ADR-FORMAT.md). + +## Repository documentation requirements + +Follow [docs/README.md](../../../docs/README.md) for every change in this workflow. Create or update +ADRs for resolved durable decisions, keep affected README/setup/public docs current, +and maintain the complete pending or PR-numbered update record after every revision. +Use the shared templates and section names. Missing or stale required documentation +blocks completion. Document already authorized decisions without asking again; ask +only about unresolved choices. These requirements govern documentation instructions +elsewhere in this skill; preserve its repository-specific implementation and checks. diff --git a/.agents/skills/improve-codebase-architecture/SKILL.md b/.agents/skills/improve-codebase-architecture/SKILL.md index 05984a6..6a3ee9b 100644 --- a/.agents/skills/improve-codebase-architecture/SKILL.md +++ b/.agents/skills/improve-codebase-architecture/SKILL.md @@ -1,10 +1,20 @@ --- name: improve-codebase-architecture -description: Find deepening opportunities in a codebase, informed by the domain language in CONTEXT.md and the decisions in docs/adr/. Use when the user wants to improve architecture, find refactoring opportunities, consolidate tightly-coupled modules, or make a codebase more testable and AI-navigable. +description: Find deepening opportunities in a codebase, informed by the domain language in CONTEXT.md and the decisions in docs/adrs/. Use when the user wants to improve architecture, find refactoring opportunities, consolidate tightly-coupled modules, or make a codebase more testable and AI-navigable. --- # Improve Codebase Architecture +## Repository documentation requirements + +Follow [docs/README.md](../../../docs/README.md) for every change in this workflow. Create or update +ADRs for resolved durable decisions, keep affected README/setup/public docs current, +and maintain the complete pending or PR-numbered update record after every revision. +Use the shared templates and section names. Missing or stale required documentation +blocks completion. Document already authorized decisions without asking again; ask +only about unresolved choices. These requirements govern documentation instructions +elsewhere in this skill; preserve its repository-specific implementation and checks. + Surface architectural friction and propose **deepening opportunities** — refactors that turn shallow modules into deep ones. The aim is testability and AI-navigability. ## Glossary @@ -67,5 +77,5 @@ Side effects happen inline as decisions crystallize: - **Naming a deepened module after a concept not in `CONTEXT.md`?** Add the term to `CONTEXT.md` — same discipline as `/grill-with-docs` (see [CONTEXT-FORMAT.md](../grill-with-docs/CONTEXT-FORMAT.md)). Create the file lazily if it doesn't exist. - **Sharpening a fuzzy term during the conversation?** Update `CONTEXT.md` right there. -- **User rejects the candidate with a load-bearing reason?** Offer an ADR, framed as: _"Want me to record this as an ADR so future architecture reviews don't re-suggest it?"_ Only offer when the reason would actually be needed by a future explorer to avoid re-suggesting the same thing — skip ephemeral reasons ("not worth it right now") and self-evident ones. See [ADR-FORMAT.md](../grill-with-docs/ADR-FORMAT.md). +- **A candidate is rejected for a durable reason:** record the resolved decision and rationale in the governing ADR so later work does not repeat the same proposal. Skip ephemeral reasons and self-evident implementation choices. Ask only when the underlying decision is unresolved. - **Want to explore alternative interfaces for the deepened module?** See [INTERFACE-DESIGN.md](INTERFACE-DESIGN.md). diff --git a/.agents/skills/maintain-docs/SKILL.md b/.agents/skills/maintain-docs/SKILL.md new file mode 100644 index 0000000..d0888ee --- /dev/null +++ b/.agents/skills/maintain-docs/SKILL.md @@ -0,0 +1,23 @@ +--- +name: maintain-docs +description: Maintain repository ADRs, change and PR update records, and affected setup/public docs while implementing or reviewing changes. +--- + +# Maintain repository documentation + +Follow [docs/README.md](../../../docs/README.md), the shared documentation contract. +Read governing ADRs before implementation. Write accepted durable decisions in +`docs/adrs/`; amend current text and append timestamped history when they change. +Record already authorized decisions directly and ask only about unresolved choices. + +Keep one complete update record using [the template](../../../docs/updates/template.md). +Before a PR exists, use `docs/updates/pending/.md`. After the authorized +PR is opened, rename it to `docs/updates/.md` using the verified +number and URL. Refresh it after each revision; never invent a number or publish +solely to obtain one. + +Review affected READMEs, setup/deployment instructions, generated contracts, and +public documentation. Update them in the same change, linking related repository +records and deployment order when applicable. Before handoff, compare the docs with +the complete final diff and report actual validation and remaining work. Missing +or stale required documentation blocks completion. Release notes remain separate. diff --git a/.agents/skills/pre-commit-checks/SKILL.md b/.agents/skills/pre-commit-checks/SKILL.md new file mode 100644 index 0000000..5033092 --- /dev/null +++ b/.agents/skills/pre-commit-checks/SKILL.md @@ -0,0 +1,26 @@ +--- +name: pre-commit-checks +description: Validate the affected diff and required documentation before committing or completing a pull request. +--- + +# Pre-commit checks + +## Repository documentation requirements + +Follow [docs/README.md](../../../docs/README.md) for every change in this workflow. Create or update +ADRs for resolved durable decisions, keep affected README/setup/public docs current, +and maintain the complete pending or PR-numbered update record after every revision. +Use the shared templates and section names. Missing or stale required documentation +blocks completion. Document already authorized decisions without asking again; ask +only about unresolved choices. These requirements govern documentation instructions +elsewhere in this skill; preserve its repository-specific implementation and checks. + +Inspect the complete task diff and preserve unrelated changes. Read the repository +instructions and run checks appropriate to the affected components. Fix in-scope +failures and distinguish pre-existing failures and unavailable external checks. + +Follow `maintain-docs` before handoff: review governing ADRs, update durable decisions, +keep affected README/setup/public docs accurate, and refresh the current update +record. A missing or stale required record blocks completion. Check formatting, +links, generated artifacts, release-note obligations, and the final diff. Report +only checks actually run; do not publish or merge without existing authorization. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..a811359 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,15 @@ +# Summary + +Describe the problem and resulting behavior. + +# Validation + +List focused checks actually run and any remaining work. + +## Documentation + +- Link the current `docs/updates/.md` record (rename the pending record after PR creation). +- Link new or amended ADRs under `docs/adrs/`, or state `ADR review: no new decision` with a reason. +- List affected README, setup/deployment, and public documentation changes; link related repository PRs and merge order. +- Confirm the update record describes the full current diff, actual validation, and required consumer/operator actions. +- Refresh this section and the same update record after subsequent review or rebase changes. diff --git a/.gitmodules b/.gitmodules index f56c3a1..0a19833 100644 --- a/.gitmodules +++ b/.gitmodules @@ -1,5 +1,5 @@ [submodule "docs"] - path = docs + path = public-docs url = https://github.com/trytilde/docs [submodule "harness-shop"] path = harness-shop diff --git a/AGENTS.md b/AGENTS.md index 062767a..9a7b13c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -21,7 +21,7 @@ CLI Factory is an agent-first Go CLI for discovering and invoking curated SaaS/t - Root `secrets.yaml` is plaintext and gitignored. Use `make sops-encrypt` / `make sops-decrypt` to manage `secrets.enc.yaml` and `.env.secrets`. - `OPENAI_API_KEY` for `make generate-catalog` can come from `.env.secrets`. - Catalogue embeddings are embedded as `catalog/embeddings.bin`, a compact float32 binary index. The JSON file is only the manifest. -- Human docs are generated into the `docs/` git submodule, which points at the shared `trytilde/docs` Mintlify repo. `make generate-docs` initializes the submodule before writing generated pages. +- Human docs are generated into the `public-docs/` git submodule, which points at the shared `trytilde/docs` Mintlify repo. `make generate-docs` initializes the submodule before writing generated pages. ## Required Checks @@ -34,3 +34,14 @@ make build ``` Use `make build-all` before release-sensitive changes. + +## Required documentation maintenance + +For every change, follow [docs/README.md](docs/README.md). Read relevant +`docs/adrs/` first; create or update records for durable decisions and keep setup, +README, and public documentation in sync. Maintain the complete change record at +`docs/updates/pending/.md` until a PR number exists, then rename it to +`docs/updates/.md` and refresh it after every revision. Missing +or stale required documentation blocks completion. Record already authorized +decisions directly; ask only about unresolved choices. See +[maintain-docs](.agents/skills/maintain-docs/SKILL.md) for the workflow. diff --git a/Makefile b/Makefile index 8a5bb67..28ebfb0 100644 --- a/Makefile +++ b/Makefile @@ -4,7 +4,7 @@ export BASH_ENV := $(HOME)/.bashrc SOPS_KMS_ARN ?= arn:aws:kms:us-east-1:914788356809:alias/tilde-app-dev-sops CATALOG_EMBEDDING_MODEL ?= text-embedding-3-small CATALOG_EMBEDDING_DIMENSIONS ?= 768 -DOCS_REPO_DIR ?= docs +DOCS_REPO_DIR ?= public-docs .PHONY: test test-unit test-e2e test-provider test-provider-tool ensure-docs-submodule generate-metadata generate-docs generate-catalog generate-catalog-provider generate-catalog-tool build build-all sops-encrypt sops-decrypt env-secrets sops-encrypt-provider-test-secrets help @@ -29,7 +29,7 @@ test-provider-tool: generate-metadata ## Run e2e tests for one tool: make test-p go test ./providers/$(PROVIDER)/$(TOOL) -run TestE2E ensure-docs-submodule: ## Ensure shared docs git submodule is initialized - git submodule update --init --recursive docs + git submodule update --init --recursive public-docs generate-metadata: ## Generate static Go metadata/schema files from provider YAML go run ./tools/generatemetadata diff --git a/README.md b/README.md index 77d380c..5b29f71 100644 --- a/README.md +++ b/README.md @@ -171,3 +171,11 @@ The harness secrets form writes `providers//override_test_secrets.yaml CLI Factory is intended to become a shared catalogue of high-quality agent tools. If you want agents to use your SaaS product well, contribute a provider with a small set of thoughtful commands and real e2e tests. Star the project, open issues or PRs, and join the Tilde community on [Discord](https://discord.gg/jj7sNyCGD4). + +## Documentation locations + +Repository decisions and change records live in [docs/](docs/README.md). Shared +Mintlify pages are generated into the independent `public-docs/` submodule. Run +`git submodule sync` and `git submodule update --init --recursive public-docs` +after updating an existing checkout; `make generate-docs` initializes it as needed. +`DOCS_REPO_DIR` can select a different checkout of the shared documentation. diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..158f152 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,50 @@ +# Repository documentation + +This convention applies to every change in this repository, including documentation, +configuration, dependencies, generated contracts, and changes made during review. + +## Required workflow + +1. Read the relevant `docs/adrs/` records before changing their decisions. Keep the + owning README, setup/deployment guide, and public documentation accurate in the + same change. Link related repositories when a change crosses their boundaries. +2. Review every change for durable architecture, security, tenancy, public contract, + storage, deployment, or product decisions. Create or update an ADR when one changes. + Record already authorized decisions directly; ask only about unresolved choices. + For changes with no durable decision, state `ADR review: no new decision` and why + in the update record. Do not create empty ADRs for routine edits. +3. Maintain one update record for the complete change, not one per commit. Before a + PR number exists, use `docs/updates/pending/.md`. Once a PR is opened, + rename it to `docs/updates/.md` and fill in its verified PR URL. + Never guess a PR number or open a PR solely to satisfy this documentation rule. +4. Refresh that same record after implementation, documentation, review, rebase, or + conflict-resolution changes. Before handing off or marking a PR ready, compare + the record with the final diff and report any remaining validation or release work. + +## Records and templates + +- [Architecture decisions](adrs/README.md): `docs/adrs/NNNN-short-slug.md`. +- [Change and PR updates](updates/README.md): `docs/updates/.md`. +- [ADR template](adrs/template.md) and [update template](updates/template.md). + +Keep accepted decision history. When a decision changes, update its current text and +append an ISO-8601 timestamped entry under `Updates`, or write a superseding ADR and +link both records. Do not erase previous rationale or amendment entries. + +Update records describe the current result, verification, and required consumer or +operator actions. Use the same four sections in every repository: `Intent of the +change`, `Architecture changes`, `Summarized changes`, and `Critical to apply`. +Include a small Mermaid boundary/flow diagram in `Architecture changes`; for a +non-architectural change, show the affected documentation or component boundary and +explicitly say the runtime architecture is unchanged. Start `Critical to apply` with +an exact `yes` or `no` on its own line, then explain why. + +Do not claim checks that were not run or treat simulated provider checks as live +verification. Keep secrets, private conversations, raw task transcripts, personal +data, screenshots, generated deployment state, and local configuration out of +these records. Link safe evidence and public contracts instead. + +Documentation records complement release notes and generated API documentation; +Changesets, Changie, or other repository release processes still apply. Historical +records keep their original filenames and format; use this convention for new or +actively updated work. Plans and speculative backlogs are not accepted ADRs. diff --git a/docs/adrs/0001-repository-documentation-convention.md b/docs/adrs/0001-repository-documentation-convention.md new file mode 100644 index 0000000..a52b726 --- /dev/null +++ b/docs/adrs/0001-repository-documentation-convention.md @@ -0,0 +1,33 @@ +# ADR-0001: Shared repository documentation convention + +Status: Accepted + +## In brief + +- Use `docs/adrs` for durable decisions and `docs/updates` for complete change records. +- Apply the same templates and maintenance requirements across Tilde repositories. + +## Context + +Repository instructions differed in directory names, templates, and whether changes +required updated records. That made accepted decisions and release obligations easy +to lose between implementation and review. + +## Decision + +Adopt [the shared documentation workflow](../README.md) as requested on 2026-09-07. +Agents and PR/pre-commit skills must maintain required records as part of the change. +Draft a pending update before a PR exists, then rename it using the actual PR number. +Record decisions already authorized in the task without asking for duplicate approval. + +The shared Mintlify documentation remains an independent Git submodule at +`public-docs/`. The Makefile and Go documentation generator use that path by default; +`docs/` now holds this repository's own decision and update records. + +## Consequences + +Existing ADR identifiers and amendment history remain intact. References to the old +singular directory are updated. Each repository owns its facts; shared structure does +not mean copying another repository's architecture. Release notes and public guides +remain separate obligations. Supporting indexes/templates and pending change records +are part of the documentation setup. diff --git a/docs/adrs/README.md b/docs/adrs/README.md new file mode 100644 index 0000000..2d9338e --- /dev/null +++ b/docs/adrs/README.md @@ -0,0 +1,18 @@ +# Architecture decision records + +Follow [the repository documentation workflow](../README.md) for every change. +ADRs record durable decisions and the reasoning a future maintainer needs. + +Use the next unused sequential number in `NNNN-short-slug.md`; keep existing IDs +stable. Start from [template.md](template.md), remove instructions, and write concise +normal prose. Include context, the decision, meaningful alternatives/consequences, +and a Mermaid diagram when a relationship benefits from one. Do not add decorative +sections or diagrams. + +Record an already approved decision without asking for approval again. Ask only +when the underlying choice is unresolved. If no durable decision changed, explain +that in the change's update record instead of creating an empty ADR. + +When amending an ADR, preserve earlier history and append a chronological bullet +under `Updates`: `- YYYY-MM-DDTHH:mm:ssZ: What changed and why.` Use a new ADR when +superseding a decision would otherwise obscure its rationale, and link both records. diff --git a/docs/adrs/template.md b/docs/adrs/template.md new file mode 100644 index 0000000..5a07266 --- /dev/null +++ b/docs/adrs/template.md @@ -0,0 +1,23 @@ +# ADR-NNNN: Decision title + +Status: Accepted + +## In brief + +- State the decision and the boundary it establishes. + +## Context + +Explain the concrete problem and why the choice needs durable reasoning. + +## Decision + +Describe the accepted behavior and its owner. Link relevant contracts or records. +Add a small Mermaid diagram only when it clarifies the relationship. + +## Consequences + +Explain the material benefit, cost, alternatives rejected, and migration impact. + + diff --git a/docs/updates/README.md b/docs/updates/README.md new file mode 100644 index 0000000..026a49b --- /dev/null +++ b/docs/updates/README.md @@ -0,0 +1,26 @@ +# Change and PR updates + +Follow [the repository documentation workflow](../README.md). Each change has one +record describing its complete current result, evidence, and deployment impact. +Use [template.md](template.md). + +Before a PR exists, keep the record at `pending/.md`. When the authorized +PR is opened, read its actual number and URL from the hosting service, rename the +record to `.md`, and include it in that PR. Never fabricate a number. +Keep updating the same record through review and follow-up commits in the same PR. + +Required sections: + +1. `Intent of the change`: the concrete problem and resulting behavior. +2. `Architecture changes`: decisions and ADR links, plus a small Mermaid diagram. + If no durable decision changed, state `ADR review: no new decision` with a reason. +3. `Summarized changes`: affected crates/packages/apps/modules or documentation, + focused validation actually run, unverified flows, and material outstanding work. +4. `Critical to apply`: begin with exactly `yes` or `no` on its own line, then explain + deployment order, migration, configuration, API-consumer, or operator actions. + +A missing or stale record blocks PR completion. Before handoff, compare it with the +full current diff, link it in the PR description, and ensure required ADRs, READMEs, +setup instructions, and public documentation are included or linked across repos. +Templates, this README, and historical records are not additional records for the +current PR. Keep unrelated history intact. diff --git a/docs/updates/pending/documentation-conventions.md b/docs/updates/pending/documentation-conventions.md new file mode 100644 index 0000000..312910a --- /dev/null +++ b/docs/updates/pending/documentation-conventions.md @@ -0,0 +1,42 @@ +# Consistent documentation and agent workflows + +PR: Pending + +## Intent of the change + +Make durable decisions and complete change records discoverable and consistently +maintained across Tilde repositories throughout implementation and PR review. + +## Architecture changes + +Governing decision: [0001-repository-documentation-convention](../../adrs/0001-repository-documentation-convention.md). +Runtime architecture is unchanged by the documentation-convention changes. + +```mermaid +flowchart LR + Agent["Agent and PR workflows"] --> Convention["docs/README.md"] + Convention --> Decisions["docs/adrs"] + Convention --> Updates["docs/updates"] + Convention --> Guides["Owning README and public guides"] +``` + +## Summarized changes + +- Standardized directories, templates, and documentation maintenance instructions. +- Connected agent instructions and PR, pre-commit, architecture, and documentation skills. +- Preserved existing decision history and repaired moved local references. +- Validation: local Markdown links, balanced code fences, required update sections, changed skill frontmatter, and `git diff --check` passed. +- Prepared from the fetched default branch in an isolated worktree; unrelated checkout changes are excluded. +- Relocated the shared Mintlify submodule to `public-docs/`, preserving its commit, and updated the generator default, Makefile, README, and provider skills together. +- Focused validation: `go test ./internal/docgen ./tools/generatedocs` passed. External provider tests and catalogue generation were not run because their behavior did not change. +- Publication and PR numbering are pending; no application deployment is required. + +## Critical to apply + +yes + +Existing checkouts must run `git submodule sync` and +`git submodule update --init --recursive public-docs` after updating. Custom +automation that refers to the shared documentation at `docs/` must use +`public-docs/` or set `DOCS_REPO_DIR`. No application migration or secret change +is required. Related repositories adopt the documentation convention independently. diff --git a/docs/updates/template.md b/docs/updates/template.md new file mode 100644 index 0000000..ab9c286 --- /dev/null +++ b/docs/updates/template.md @@ -0,0 +1,31 @@ +# Change title + +PR: Pending + +## Intent of the change + +Describe the problem and resulting behavior for someone who has not read the task. + +## Architecture changes + +Link the governing/new ADRs, or state `ADR review: no new decision` and why. + +```mermaid +flowchart LR + Caller["Affected caller"] --> Owner["Owning component"] +``` + +Replace the diagram with this change's actual boundaries or documentation flow. + +## Summarized changes + +- Describe affected components and why they changed. +- Record focused validation actually run and its result. +- State unverified flows, related repository changes, and outstanding work. + +## Critical to apply + +no + +Replace with `yes` when consumers/operators must act. Explain configuration, +migration, deployment order, compatibility, or why no action is required. diff --git a/docs b/public-docs similarity index 100% rename from docs rename to public-docs diff --git a/skills/add-provider/SKILL.md b/skills/add-provider/SKILL.md index 241a5a1..a4dc81a 100644 --- a/skills/add-provider/SKILL.md +++ b/skills/add-provider/SKILL.md @@ -30,7 +30,7 @@ Use this skill when creating a new provider under `providers/` or addi - `internal/testharness` - `Makefile` 4. Inspect shared Mintlify docs conventions: - - `docs/` git submodule + - `public-docs/` git submodule - `DOCS_REPO_DIR` - `/docs.json` - `internal/docgen` @@ -120,7 +120,7 @@ providers// Use hyphenated command directories, for example `send-email`, because the directory mirrors the command path. Use valid Go package names inside files. -Mintlify human documentation is generated from these metadata and schema files into the `docs/` git submodule for the shared `trytilde/docs` repo: +Mintlify human documentation is generated from these metadata and schema files into the `public-docs/` git submodule for the shared `trytilde/docs` repo: ```text /projects/cli-factory/providers//index.mdx diff --git a/skills/update-provider/SKILL.md b/skills/update-provider/SKILL.md index f564ca4..d746cfd 100644 --- a/skills/update-provider/SKILL.md +++ b/skills/update-provider/SKILL.md @@ -31,7 +31,7 @@ Read: - affected tool directories - affected `input-schema.yaml` and `output-schema.yaml` - affected `e2e_test.go` -- generated Mintlify docs under `docs/projects/cli-factory/providers//` +- generated Mintlify docs under `public-docs/projects/cli-factory/providers//` - recent invocation logs if the user provided a failing command output Also inspect: @@ -40,7 +40,7 @@ Also inspect: - `internal/docgen` - `Makefile` - `.gitignore` -- shared docs submodule `docs/docs.json` +- shared docs submodule `public-docs/docs.json` - relevant `CONTEXT.md` terms and ADRs If the repo already has behavior that conflicts with the requested update, surface it before editing. diff --git a/tools/generatedocs/main.go b/tools/generatedocs/main.go index a0ad98d..f9ab482 100644 --- a/tools/generatedocs/main.go +++ b/tools/generatedocs/main.go @@ -17,7 +17,7 @@ func main() { } } if docsRoot == "" { - docsRoot = filepath.Clean("docs") + docsRoot = filepath.Clean("public-docs") } if err := docgen.GenerateTo(docgen.Options{SourceRoot: ".", DocsRoot: docsRoot}); err != nil { fmt.Fprintln(os.Stderr, err) From 40cb410d8a1f0ca4a1564dbfe4ec0b783f950fbb Mon Sep 17 00:00:00 2001 From: Daniel Blignaut Date: Mon, 7 Sep 2026 16:20:43 +0200 Subject: [PATCH 2/3] docs: bind update record to pull request --- docs/updates/{pending/documentation-conventions.md => 2.md} | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) rename docs/updates/{pending/documentation-conventions.md => 2.md} (89%) diff --git a/docs/updates/pending/documentation-conventions.md b/docs/updates/2.md similarity index 89% rename from docs/updates/pending/documentation-conventions.md rename to docs/updates/2.md index 312910a..7807175 100644 --- a/docs/updates/pending/documentation-conventions.md +++ b/docs/updates/2.md @@ -1,6 +1,6 @@ # Consistent documentation and agent workflows -PR: Pending +PR: https://github.com/trytilde/cli-factory/pull/2 ## Intent of the change @@ -9,7 +9,7 @@ maintained across Tilde repositories throughout implementation and PR review. ## Architecture changes -Governing decision: [0001-repository-documentation-convention](../../adrs/0001-repository-documentation-convention.md). +Governing decision: [0001-repository-documentation-convention](../adrs/0001-repository-documentation-convention.md). Runtime architecture is unchanged by the documentation-convention changes. ```mermaid @@ -29,7 +29,7 @@ flowchart LR - Prepared from the fetched default branch in an isolated worktree; unrelated checkout changes are excluded. - Relocated the shared Mintlify submodule to `public-docs/`, preserving its commit, and updated the generator default, Makefile, README, and provider skills together. - Focused validation: `go test ./internal/docgen ./tools/generatedocs` passed. External provider tests and catalogue generation were not run because their behavior did not change. -- Publication and PR numbering are pending; no application deployment is required. +- Published as a draft PR with this record renamed to its verified PR number. No application deployment is required. ## Critical to apply From a4777c275a978ee6463934c99b50238db049797c Mon Sep 17 00:00:00 2001 From: Daniel Blignaut Date: Mon, 7 Sep 2026 16:24:56 +0200 Subject: [PATCH 3/3] docs: document initialized submodule migration --- README.md | 16 +++++++++++++--- .../0001-repository-documentation-convention.md | 4 ++++ docs/updates/2.md | 7 ++++--- 3 files changed, 21 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 5b29f71..011a22e 100644 --- a/README.md +++ b/README.md @@ -175,7 +175,17 @@ Star the project, open issues or PRs, and join the Tilde community on [Discord]( ## Documentation locations Repository decisions and change records live in [docs/](docs/README.md). Shared -Mintlify pages are generated into the independent `public-docs/` submodule. Run -`git submodule sync` and `git submodule update --init --recursive public-docs` -after updating an existing checkout; `make generate-docs` initializes it as needed. +Mintlify pages are generated into the independent `public-docs/` submodule. `DOCS_REPO_DIR` can select a different checkout of the shared documentation. + +When updating an existing checkout that still uses the old `docs/` submodule, +commit or back up any submodule changes first, then run `git submodule deinit docs` +**before** switching to this revision. Do not force deinitialization past local +changes. After updating the branch, run `git submodule sync` and +`git submodule update --init --recursive public-docs`; `make generate-docs` +initializes the new location as needed. Fresh clones only need the latter update. + +If an existing checkout was updated before deinitialization, the old submodule may +leave a stale `docs/.git` and shared-documentation files behind. Preserve that +checkout's changes before cleaning up the old files. Do not remove the entire +`docs/` directory: it now contains tracked repository records. diff --git a/docs/adrs/0001-repository-documentation-convention.md b/docs/adrs/0001-repository-documentation-convention.md index a52b726..231fa19 100644 --- a/docs/adrs/0001-repository-documentation-convention.md +++ b/docs/adrs/0001-repository-documentation-convention.md @@ -31,3 +31,7 @@ singular directory are updated. Each repository owns its facts; shared structure not mean copying another repository's architecture. Release notes and public guides remain separate obligations. Supporting indexes/templates and pending change records are part of the documentation setup. + +## Updates + +- 2026-09-07T14:24:55Z: An initialized-submodule fixture showed that switching revisions before deinitialization leaves stale files under `docs/`. Existing checkouts must preserve changes and deinitialize the old path before updating. diff --git a/docs/updates/2.md b/docs/updates/2.md index 7807175..0495807 100644 --- a/docs/updates/2.md +++ b/docs/updates/2.md @@ -28,15 +28,16 @@ flowchart LR - Validation: local Markdown links, balanced code fences, required update sections, changed skill frontmatter, and `git diff --check` passed. - Prepared from the fetched default branch in an isolated worktree; unrelated checkout changes are excluded. - Relocated the shared Mintlify submodule to `public-docs/`, preserving its commit, and updated the generator default, Makefile, README, and provider skills together. -- Focused validation: `go test ./internal/docgen ./tools/generatedocs` passed. External provider tests and catalogue generation were not run because their behavior did not change. +- Focused validation: `go test ./internal/docgen ./tools/generatedocs` passed. A temporary initialized-submodule fixture verified that deinitializing the old path before updating avoids stale nested repository files and leaves a clean checkout. External provider tests and catalogue generation were not run because their behavior did not change. - Published as a draft PR with this record renamed to its verified PR number. No application deployment is required. ## Critical to apply yes -Existing checkouts must run `git submodule sync` and -`git submodule update --init --recursive public-docs` after updating. Custom +Before updating an existing checkout, preserve submodule changes and run +`git submodule deinit docs` without force. After updating, run `git submodule sync` +and `git submodule update --init --recursive public-docs`. Custom automation that refers to the shared documentation at `docs/` must use `public-docs/` or set `DOCS_REPO_DIR`. No application migration or secret change is required. Related repositories adopt the documentation convention independently.