Repository navigation
Update Context Architecture for the 2026 agent landscape - #2
Merged
Merged
Conversation
Commit the pending dependency bump (vitest 5, pnpm 12.4.1, Nuxt UI 4.11, oxlint 1.82, etc.) and fix the stale claims it left, plus the context-rot the audit found in the repo's own docs: - content/AGENTS.md described routes /en and /es/comparison that the site never serves; the map now reflects the prefix_except_default strategy and the localized ES slugs. - nuxt.config.ts promised /llms_full.txt; the module emits /llms-full.txt. - deploy.yml no longer hard-codes the pnpm major (read from packageManager). - pnpm-workspace.yaml minimumReleaseAgeExclude pruned (entries matched nothing). Derive the site's routes once in app/site-routes.ts, consumed by i18n.pages and the prerender list, so the router and the static output cannot drift from the content tree (principle 05). Document the agent-facing /raw/**.md mirror in the root and server AGENTS.md (it was emitted by @nuxt/content with nothing saying so) and link the raw manifesto from llms.txt. Broaden the mechanisms: - tests/doc-references.test.ts now discovers every AGENTS.md, resolves bare source filenames and directories, checks the components and composables app/AGENTS.md names, asserts every test is documented and every nested AGENTS.md is mapped, that specs/ stays absent, and that each CLAUDE.md bridges to its AGENTS.md; it also self-tests that the check can fail. - tests/routes.test.ts binds app/site-routes.ts to the content tree, the prerender list, the internal links, and the prerendered HTML. - tests/prerendered-no-js.test.ts binds that /raw/en.md and /raw/es.md carry the rule.
The citable definition circulated in three English wordings (the frontmatter and glossary said 'that claim', the site and llms descriptions said 'the claim', the README a third variant) and the meta description dropped the mechanism clause that distinguishes Context Architecture. The published HTML shipped two wordings. A claim the repo makes about itself, unbound, which the rule calls the violation. - Move CANONICAL_DEFINITION (and the derived SITE_DESCRIPTION) into the pure module app/site-definition.ts, imported by nuxt.config.ts and re-exported by useManifestoSchema for the schema composables. - site.description, llms.description, and the llms canonical section now derive from that one string; the index.md meta description carries the mechanism clause; the README opens with the canonical definition. - tests/canonical-definition.test.ts binds it: the frontmatter, glossary, feed descriptions, and README carry it verbatim, and the prerendered HTML never ships a divergent wording.
…ete the glossary Terminology and positioning, so the site stays citable as the field's vocabulary settled (all sources verified 2026-09-15): - Context Architecture: the glossary and comparison now name the three rival public senses of the phrase (data-platform metadata, Modern Data 101; the runtime context window, Atlan; information architecture, NN/G) and scope the attribution to the repository sense, coined October 2025, published June 2026. The DefinedTerm gains disambiguatingDescription and the TechArticle gains dateCreated (the coinage date), which structured-data.test.ts now binds. - Harness engineering: rewritten to match how OpenAI (Feb 2026) and Thoughtworks (Böckeler, Apr 2026) use the term, which reaches into the repository. The comparison redraws the boundary around what Context Architecture owns: the rule, prose claims bound, and principle 09. New sections cover OpenAI's usage, readiness scorecards, and dated related work. - Context rot: kept, with the two senses named (Chroma and Anthropic for the context window; Treude and Baltes, and this spec, for repository drift); hyphen dropped. - New glossary entries with the vocabulary readers now arrive with: mechanism (its fitness-function lineage), hook, skill, progressive disclosure, agent memory, agentic engineering, agent readiness. Each with a schema.org DefinedTerm. Content parity holds (EN and ES both carry the new headings and terms).
Add framing to the manifesto and its llms.txt echo without touching any of the nine principles' names, numbering, or mechanism lines: - Where a mechanism fires (agent-loop hook, push rules, or CI) is the infrastructure's choice; firing early does not replace the integration gate, because a hook can be switched off locally. - Review by an agent counts only when its verdict can stop the change, and the agent reviewer runs in a fresh context. - Agent memory exists now but lives outside the repository, unverified and unshared, so the memoryless reader is still the one to design for. - The rule notes that a test's ability to fail is itself a claim (mutation testing). - The autonomy spectrum names the four levels as 2026 products and the merge queue as where parallel agents' changes are arbitrated. - Principle 02 acknowledges path-scoped rule files as the same claim in a central-folder layout; 07 that a convention can be about configuration; 09 that the authorization is the repo's integration rules and that an agent's approval never authorizes a change to the verification surface. - The problem cites the 2026 AGENTS.md studies; content/AGENTS.md now permits cited third-party figures, never attributed to Context Architecture. The guide callout gains the memory stance. EN and ES stay in parity.
The guide's most-differentiated step, principle 09, had no concrete mechanism, several agents never discover nested AGENTS.md, and 'keep it short' had no number while hard tool budgets exist. This adds the missing procedure and binds the size claim: - New Path B step 8 (and Path A step 7): bind the verification surface with four named mechanisms (a test over the checks, a check that can fail via mutation testing, CODEOWNERS plus a ruleset, an edit-time deny hook). - Step 3: the root AGENTS.md is a map that lists every nested file (agents differ in what they discover), with dated size budgets (32 KiB chain, 12,000-char file, ~200 lines); the template gains ## Commands and ## Boundaries; path-scoped rule files are the same claim in a central layout; and what goes in a skill vs an AGENTS.md. - Step 2: scan the path-scoped rule folders and SKILL.md files, and name the context-file linter class. - Step 4: the import-boundary tool class, the same rule wired at edit/commit/CI, and the shrink-only baseline for brownfield. - tests/agents-md-budget.test.ts binds the budget: no file over 12,000 chars, no root-to-leaf chain over 32 KiB. 'context-rot' loses its hyphen here too. EN and ES stay in parity (21 headings).
…s spec
Distribution, so the adoption page and the skill match the 2026 ecosystem:
- content/{en,es}/skill.md 'Install it' is rebuilt around the converged
.agents/skills/<name>/SKILL.md path (read by 15 agents, dated), with the one
command, Claude Code, GitHub Copilot (VS Code and JetBrains), tool-specific
directories (Cline, Kiro, Qwen), and the Claude Code plugin install the page
never documented. Drops the stale Cursor .mdc rule and the Windsurf/Cline/Zed
rule instructions (all read SKILL.md now). 'Keep it updated' names
�[38;5;145mChecking for skill updates…�[0m
�[38;5;102mNo global skills tracked in lock file.�[0m
�[38;5;102mInstall skills with�[0m �[38;5;145mnpx skills add <package> -g�[0m and .
- SKILL.md gains metadata.version, quoted term-introduced, first-published, and
the SPDX license id; the description gains discovery triggers; the body echoes
the manifesto framing (memory, where a mechanism fires, agent review, mutation
testing) and rewrites Phase 4 to a mechanism, not a reminder. Trimmed to stay
under the ~5000-token budget. context-rot loses its hyphen.
- marketplace.json bumps to 0.3.0 and declares its schemastore schema.
- tests/skill-spec.test.ts binds spec conformance (name, description length,
string metadata, standard keys, size budget); skill-version.test.ts now also
checks the frontmatter version and pins the 0.3.0 hash.
Parity holds (11 headings each); claude plugin validate . --strict passes.
The repo is its own first case study but did not declare the authorization principle 09 names. This adds the in-repo half: - .github/CODEOWNERS marks the verification surface (tests/, lint and format config, vitest.config.ts, .github/, .claude/, .claude-plugin/) as owned. - REVIEW.md states the review rules AI reviewers and people apply on every change (docs that lie, loose claims, a weakened surface, broken parity). - tests/verification-surface.test.ts now also checks CI runs on pull requests, CODEOWNERS covers the surface, and the runner still collects every test. - AGENTS.md documents the three-layer authorization and the branch ruleset to create with gh api (the external half). The committed agent deny-rule settings file and the ruleset land in follow-ups.
Turn conventions that held 'by discipline' into mechanisms, and remove two
standing warnings:
- .oxlintrc.json enables complexity, max-depth, max-params, and
max-lines-per-function at error (principle 04), set as a ratchet at the levels
the current code passes, and promotes tailwindcss/no-hardcoded-colors from warn
to error (principle 07). verification-surface.test.ts pins all of them.
- prose-conventions.test.ts binds the one-accent-color rule: no hard-coded hex or
rgb() in app/**/*.{vue,ts} outside the tokens and the OgImage renderer, and
main.css defines --ca-accent once per color scheme. app/AGENTS.md documents the
OgImage exemption.
- Code comments are now all English (the convention is stated in AGENTS.md); the
Spanish comments in nuxt.config.ts and wrangler.jsonc are translated.
- seo.validateAppHead is off, with the per-locale html lang now bound in
prerendered-no-js.test.ts, so typecheck no longer prints a standing warning.
AGENTS.md updates which principles are bound vs held by discipline.
…enerate the command list - AGENTS.md and app/AGENTS.md stop calling Lighthouse 100 and accessibility a 'floor' or 'hard rule'. They are quality targets checked by hand with tooling (Lighthouse, axe) before a visual change, not rules bound in CI. By the repo's own rule, an unbound check stated as a rule is the violation, so this states it as what it is. - tests/capabilities.test.ts now also checks the other direction of principle 05: every package.json script except lifecycle hooks is documented. build, preview, and cf:preview, previously undocumented, are added to the AGENTS.md command list.
- robots.txt declares the AI content signals search=yes, ai-input=yes, ai-train=yes (the site wants to be indexed, cited, and in the training corpora). The directive is a per-group property, verified against the built output. - public/_headers serves /skill.md as text/markdown; charset=utf-8 (Workers Assets drops the handler header, and the skill contains non-ASCII); its stray em dash is fixed. public/_redirects sends /sitemap.xml to the sitemap index. - The author Person gains jobTitle, worksFor, and knowsAbout; the TechArticle gains image, mainEntityOfPage, isPartOf, and Wikidata mentions (software architecture, AI agent, context engineering) so a knowledge graph can resolve and place the entity. - The deploy workflow asks the Wayback Machine to snapshot the published URLs, so the definition and its dates carry a neutral third-party timestamp (attribution). - tests/geo-surface.test.ts binds the charset headers, the sitemap redirect, and the robots content signals; structured-data.test.ts binds the Wikidata anchors and the filled-out author. Deferred (noted for follow-up): merging the two JSON-LD blocks into one graph, per-page git dateModified with a visible date, localizing the /es WebSite description, and the llms.txt link-list restructure.
Heading count alone let a paragraph, a mechanism line, a table row, a code span, or a link vanish in translation. content-parity.test.ts now also checks, per page and per locale, the count of mechanism markers, table rows, fenced blocks, internal links, and code spans, plus the frontmatter keys. content/AGENTS.md records the dimensions the parity mechanism binds.
… (principle 09) Complete the principle-09 authorization: .claude/settings.json (committed) denies the agent editing the verification surface (.oxlintrc.json, .oxfmtrc.json, vitest.config.ts, .github/, .claude/settings.json, .claude-plugin/), so a person edits those by hand. tests/ stays writable so tests can be added, and the test-collection and test-documentation checks catch a deletion. This is the edit-time layer under CODEOWNERS and the branch ruleset. verification-surface.test.ts asserts the deny rules, and AGENTS.md now cites the file by path.
…ontext engineering to Wikidata Three deferred GEO items that live in the tree: - The sitewide WebSite description is localized, so the /es schema is no longer in English (SITE_DESCRIPTION_ES, overridden by @id in app.vue). - og:image:alt gives the generated OG image a localized text alternative. - The context engineering DefinedTerm carries sameAs to its Wikidata entity, so an engine can resolve the adjacent term.
The DefinedTermSet, DefinedTerm, and TechArticle nodes were emitted as a separate useHead JSON-LD block, so a consumer that reads blocks one at a time saw a TechArticle whose author @id resolved only in the other block. Emit them through useSchemaOrg instead, so they join @nuxtjs/seo's WebSite/WebPage/Person in a single @graph: every cross-@id reference (the WebPage subject, the article author, the term set) now resolves inside one block. structured-data.test.ts asserts each page emits exactly one ld+json block.
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.
Brings Context Architecture up to date with the agent-development landscape as of September 2026, and closes the gaps the site's own skill flags when run against this repo. Research was done across seven dated lenses; the load-bearing facts were verified by hand (GitHub API, the live site, vendor docs, arXiv, Wikidata) because the adversarial-verification pass could not finish.
The core holds and is unchanged: the rule, the nine principles, the mechanism taxonomy, the autonomy-spectrum thesis, tool-neutrality, AGENTS.md per boundary, the skill layout, and the version-hash chain.
What changed, by commit
/enand/es/comparisonthat never existed, the/llms_full.txttypo). Routes are derived once inapp/site-routes.ts; the/raw/**.mdmirror is documented and bound.app/site-definition.ts; the HTML no longer ships two wordings./skillrebuilt around.agents/skills/; skill to v0.3.0 with spec conformance bound..claude/settings.jsondeny rules over the verification surface, all bound byverification-surface.test.ts./skill.mdcharset, sitemap redirect, one JSON-LD graph, Wikidata anchors, a filled-out author, a localized/esschema,og:image:alt, and a Wayback archive step.Verified
pnpm lint,pnpm format:check,pnpm typecheck,pnpm generate, andpnpm test(82 tests) all pass, andclaude plugin validate . --strictpasses.Follow-ups a person must do (outside the tree)
Create the
mainbranch ruleset; confirm Cloudflare leaves AI bots in Allow and add thewwwCNAME; update the GitHub repo description; verify Bing and Google; PR the v0.3.0 skill to thedavila7mirror; and add the cross-links on sergioazocar.com. One in-repo item is intentionally left to the owner: per-pagedateModifiedneedsfetch-depth: 0in the deploy workflow, which the principle-09 deny rules reserve for a person.🤖 Generated with Claude Code
https://claude.ai/code/session_01LqnKHkaKCREed1bq56vzh2