docs: migrate cross-repo standards from ai-assistant-instructions#32
Merged
Conversation
Move 10 of 14 rule files (~71%) from JacobPEvans/ai-assistant-instructions agentsmd/rules/ into the public docs site. The flaky agent-only loading mechanism is the wrong home for standards humans need to read; this PR puts CI/CD policy, git signing, Terraform check placement, Nix package placement, scrubbed-values, no-scripts, commit conventions, diagramming, and Bifrost routing into docs.jacobpevans.com where they belong. New pages: - infrastructure/cicd/policy.mdx (folds in PR #654's on-prem runner rules) - infrastructure/cicd/git-signing.mdx - infrastructure/terraform-check-placement.mdx - nix/package-placement.mdx - security/scrubbed-values.mdx - conventions/ group: overview, commit-conventions, no-scripts, diagramming Existing pages absorb the rest: - security/golden-laws.mdx: law 1, 3, 8, 15 enforcement links repointed - security/overview.mdx: scrubbed-values card added - infrastructure/cicd/overview.mdx: links to policy + git-signing + tf-checks - architecture/ai-pipeline.mdx: Bifrost/PAL local-AI-gateway section added - ai-development/ai-assistant-instructions.mdx: scope-narrows what ai-assistant-instructions owns (AI-runtime only); points to Conventions Verification: - jq empty docs.json passes - Canonical Mermaid theme directive count: 1 (unchanged) - 35 internal links all resolve to existing or new pages - No real IPs / account IDs / tokens introduced - No new private-repo references introduced Follow-up in JacobPEvans/ai-assistant-instructions (separate PR): - Delete the 10 migrated rule files - Update remaining cross-references to point at docs.jacobpevans.com - Close PR #654 in favor of this migration Assisted-by: Claude <noreply@anthropic.com>
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces a comprehensive suite of documentation pages defining cross-repo standards for commit conventions, Mermaid diagramming, script placement, and CI/CD policies. It also establishes security guidelines for Git signing and the use of scrubbed values for sensitive data placeholders. The navigation structure has been updated to integrate these new sections. Review feedback focuses on maintaining consistency between the order of cross-reference cards and the site's navigation hierarchy defined in docs.json, as well as ensuring macOS security command examples include absolute keychain paths to prevent lookup failures.
Non-default keychains (ai-secrets, automation, elevate-access) require the absolute path as the final positional argument; without it, the command searches only the default login keychain and the lookup fails. Assisted-by: Claude <noreply@anthropic.com>
JacobPEvans
added a commit
to JacobPEvans/ai-assistant-instructions
that referenced
this pull request
May 24, 2026
) The agentsmd/rules/ folder accreted human-readable cross-repo standards that should not be locked inside an agent-only loading mechanism. JacobPEvans/docs#32 moves them to the public docs site; this PR removes the source files (and trims soul.md to AI-specific voice/autonomy only). Deleted (full content now on docs.jacobpevans.com): - ci-cd-policy.md -> /infrastructure/cicd/policy - git-signing.md -> /infrastructure/cicd/git-signing - terraform-checks-placement.md -> /infrastructure/terraform-check-placement - nix-package-placement.md -> /nix/package-placement - no-scripts.md -> /conventions/no-scripts - diagramming.md -> /conventions/diagramming - secrets-policy.md -> absorbed into /security/golden-laws + /security/overview - config-secrets.md -> /security/scrubbed-values - bifrost-routing.md -> absorbed into /architecture/ai-pipeline Edited: - soul.md: dropped commit/PR subject conventions (no-emoji, Conventional Commits) - now in /conventions/commit-conventions. Voice and autonomy bullets stay because they're AI-runtime behavior, not commit shape. - AGENTS.md: 'no-scripts.md' and 'diagramming.md' references repointed to docs URLs. - docs/diagrams.md: rule-file lists in the architecture and lifecycle diagrams updated to reflect the surviving four rules (tool-use, soul, skill-execution-integrity, nix-tool-policy). The Nix loader (`discoverMarkdownFiles` in JacobPEvans/nix-ai/modules/claude-config.nix) globs all .md files in agentsmd/rules/, so deleted files just stop loading - no manifest to update. Refs: JacobPEvans/docs#32 Closes #654 (folded into JacobPEvans/docs#32's policy.mdx) Assisted-by: Claude <noreply@anthropic.com>
This was referenced May 24, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
JacobPEvans/ai-assistant-instructions/agentsmd/rules/into the public docs site. The flaky agent-only loading mechanism is the wrong home for standards humans need to read.ai-assistant-instructionsPR #654 (on-prem self-hosted runner exception) into the newinfrastructure/cicd/policy.mdxpage so it lands as part of the migration.What moved
ci-cd-policy.md+ PR #654infrastructure/cicd/policy.mdxgit-signing.mdinfrastructure/cicd/git-signing.mdxterraform-checks-placement.mdinfrastructure/terraform-check-placement.mdxnix-package-placement.mdnix/package-placement.mdxno-scripts.mdconventions/no-scripts.mdxsoul.md(commit/PR portion)conventions/commit-conventions.mdxsecrets-policy.mdsecurity/golden-laws.mdx+security/overview.mdxconfig-secrets.mdsecurity/scrubbed-values.mdxdiagramming.mdconventions/diagramming.mdx(links to this repo'sAGENTS.mdfor the canonical Mermaid style guide)bifrost-routing.mdarchitecture/ai-pipeline.mdxStays in
agentsmd/rules/because it is AI-runtime only:tool-use.md,skill-execution-integrity.md,nix-tool-policy.md, residualsoul.md(voice/autonomy),infra/subdir.Voice adjustments per page
The rule files were written in agent-instruction voice ("you MUST", banned/allowed tables). On the docs site they're reframed in active second-person voice with pull-quote openers, Mintlify CardGroup "where to go next" sections, and
tier:frontmatter matching the existing site convention. Substance — runner-label catalogs, the four-tier search, the placement matrix, the scrubbed-values table — is preserved verbatim.Verification
jq empty docs.jsonpasses192.168.0.*,2001:db8::*,example.com,<token>only)gh repo viewconfirms everyJacobPEvans/*reference in the diff is PUBLIC; the pre-existingterraform-awslink ininfrastructure/cicd/terraform-runs-on.mdxis unchanged by this PR and out of scope here)Test plan
mint devand click every new page (Conventions x4, CI/CD policy, CI/CD git-signing, terraform-check-placement, nix/package-placement, security/scrubbed-values)mint broken-linksFollow-up (separate PR in
ai-assistant-instructions)Once this lands:
soul.md)https://docs.jacobpevans.com/...agentsmd/rules/infra/subdir for references to deleted files🤖 Generated with Claude Code