Skip to content

Wikantik

The Agentic Dogfood Loop: How Requirements Enter Through Wikantik and Exit in Code Across the Ecosystem

From Wikantik · 22 articles · latest

Engineering workbench with an open illuminated technical notebook connected via fiber-optic traces to modular server units
The cybernetic feedback loop: How architectural requirements enter through Wikantik's living knowledge graph and emerge as verified production code across Pressroom, Stockroom, and Jakemon.

In almost every software engineering organization, documentation exists as a quiet cemetery. Teams set up Confluence spaces, Notion workspaces, or Google Drive folders with noble intentions. Systems architects write multi-page product requirement documents; engineers skim them once; and the moment implementation begins, code and documentation diverge forever. Six months later, the wiki is a museum of stale assumptions, abandoned schemas, and broken links. New hires are told: “Don't trust the documentation; just read the code.”

When autonomous AI coding agents enter an organization with stale documentation, this divergence turns catastrophic. Language models lack organizational intuition. If an agent is pointed at an uncurated, decaying documentation corpus, it will cheerfully ingest outdated API contracts from 2023, synthesize hallucinated abstractions, and open pull requests that shatter production invariants.

In the Simple Agility ecosystem, we rejected the documentation-as-graveyard paradigm entirely. We do not treat documentation as a post-hoc chore. Instead, Wikantik operates as the active, machine-readable requirements engine and architectural governance plane for the entire software stack. Requirements enter through the wiki as Architectural Decision Records (ADRs) and structural hubs; autonomous agents drink directly from the wiki via the Model Context Protocol (MCP); and code exits into production across multiple independent repositories. Crucially, the agents developing the rest of the stack are the very same agents maintaining Wikantik itself—establishing a tight, unrelenting dogfood loop that ruthlessly exposes architectural friction.

1. The Ecosystem Topology: Four Core Pillars and an Outreach Fleet

To understand the dogfood loop, one must first understand the architectural surface area it governs. Simple Agility is not a single sprawling monolith; it is an integrated suite of decoupled, specialized services maintained by a single human engineer (Jake) paired with autonomous agents:

  • Wikantik (~/source/jspwiki): The central knowledge base and architectural brain. Built on an enterprise Jakarta EE and Java foundation, Wikantik provides dense vector search (pgvector), hybrid BM25 retrieval, structural Page Graph navigation, and dual Model Context Protocol (MCP) endpoints serving standing briefings to AI runtimes.
  • Pressroom (~/source/pressroom): The customer communication and publishing engine. Modernized from Apache Roller 6.1.5 into a Spring Boot 4.1 executable running on Java 25 LTS, Pressroom exposes a native MCP server at /api/mcp with granular token scoping for automated editorial authoring.
  • Stockroom (~/source/stockroom): Physical warehouse management (WMS), barcode intake, pricing triage, eBay seller integration, and operator-assisted customer spotlights. Stockroom maintains zero internal pricing or taxonomy rules; it fetches listing rules and category logic live by slug from ResellingHub on Wikantik.
  • Jakemon (~/source/jakemon): The unified observability plane. A centralized, push-based monitoring architecture combining Prometheus, Loki, Grafana, Alertmanager, and host-level Grafana Alloy agents.
  • Blogger Agent (~/source/blogger-agent): The autonomous editorial and customer outreach harness that interfaces directly with Pressroom and legacy Blogger APIs under strict quality gates.

Keeping five distinct codebases coherent, synchronized, and architecturally aligned without a 50-person engineering department is impossible under manual coordination. The glue that holds them together is Wikantik.

2. The Anatomy of the Dogfood Loop

The development lifecycle of every feature, refactor, and bugfix across these repositories follows a closed cybernetic loop:

Architectural Principle (The Invariant of Closed-Loop Governance):

No production code may be authored across any repository without an authoritative architectural anchor in Wikantik. Conversely, no architectural standard in Wikantik is considered valid until it has been implemented, verified, and dogfooded by autonomous agents operating in production code.

Stage 1: Requirements Ingestion & Architectural Decision Records

Every non-trivial initiative begins not in an IDE, but on a Wikantik page. When a cross-cutting problem emerges—such as standardizing container logging, redesigning reader authentication, or decoupling background tasks—the human operator drafts or bootstraps an Architectural Decision Record (ADR) or a dedicated Hub page (such as SimpleAgilityStackHub or SimpleAgilityDecisionLog).

Unlike conversational chat prompts that vanish into scrolling history, a Wikantik ADR is permanent, version-controlled, and structurally connected to the wiki's Page Graph. It explicitly records:

  1. The concrete operational context and symptoms driving the change.
  2. The rejected alternatives and their empirical failure modes.
  3. The normative decision, stated as an immutable architectural invariant.
  4. The exact list of software clusters and repositories bound by the ruling.

Stage 2: The Session Start Invariant (get_briefing)

When an autonomous coding agent starts a session in any repository—whether tuning a database connection pool in Pressroom or adjusting a barcode scanner listener in Stockroom—the repository's governing rules mandate an unskippable first step:

{
  "server": "wikantik",
  "method": "get_briefing",
  "arguments": {
    "clusters": ["<project>"],
    "prompt": "<your first task>"
  }
}

The agent does not guess what the coding standards are. It does not scrape stale READMEs. It connects via MCP to Wikantik, which dynamically synthesizes an authoritative, three-tiered briefing tailored precisely to that project cluster.

Stage 3: Citation-Derived Context Adoption (ADR-0011 / SA-13)

The breakthrough that made this cross-cutting governance scalable was the adoption of ADR-0011: Project Context is Derived from Citations, Not Declared (ratified as decision SA-13 on the wiki).

Historically, multi-project briefings suffered from severe signal contamination. When an agent working on Pressroom asked for architectural context, vector search routinely pulled in unrelated Stockroom inventory plans simply because both mentioned “database migrations.” Conversely, global architectural contracts were frequently missed because an engineer forgot to tag a document.

Under ADR-0011, Wikantik derives project context deterministically from the Page Graph at request time:

  • Tier 1 (Core Cluster Members): The primary pages belonging to the requested cluster, ranked not by recent modification timestamps, but by in-degree centrality (how many other pages link to them). Hub documents and structural contracts appear first; incident runbooks appear last.
  • Tier 2 (Cited Contracts): Pages outside the cluster that are explicitly linked by Tier 1 members. If a Pressroom architecture page links to [[SimpleAgilityTelemetryContract]], that contract is automatically promoted to Tier 2 under ## Contracts this project cites. Writing that wikilink is the entire act of adoption. No configuration files need editing; no taxonomies require curation.
  • Elsewhere Pointers: When running in exploratory mode, vector search matches lying outside Tiers 1 and 2 are compressed into 1-line pointers under ## Elsewhere in the wiki. The agent is alerted to prior art without burning precious prompt tokens on full-text bodies.

Stage 4: Autonomous Test-Driven Implementation

Armed with an authoritative, token-efficient briefing containing both project-local specifications and cross-cutting ecosystem contracts, the agent executes the task within the local repository. Following strict Test-Driven Development (TDD), the agent writes failing tests first, implements the minimum compliant code, validates changes against local Docker testbeds, and runs local pre-commit gates.

Stage 5: The Feedback Loop Closes

As agents work in downstream repositories, they continuously stress-test Wikantik's own infrastructure. If Wikantik's MCP server latency spikes, if hybrid vector retrieval misses a key contract, or if a briefing contains ambiguous guidance, the agent's immediate operational friction flags the defect. Improvements to Wikantik are prioritized based on real friction experienced during agent development sessions.

3. Cross-Cutting Standards Enforced Across the Fleet

The true power of the Wikantik dogfood loop is cross-cutting consistency. In typical multi-repo setups, each service gradually invents its own logging formats, error handling idioms, and deployment quirks. In Simple Agility, Wikantik enforces uniform invariants across every repository:

The Universal Telemetry Contract (SA-6)

Every application in the stack—regardless of whether it is written in Java (Wikantik, Pressroom) or Go/Python/Shell (Jakemon, Stockroom, Blogger Agent)—must conform to the SimpleAgilityTelemetryContract. All containerized applications emit structured JSON logs adhering to the Elastic Common Schema (ECS), tagged with service identifiers, log levels, and trace contexts. Concurrently, every web service exposes a Prometheus /metrics endpoint.

Because this contract is governed centrally in Wikantik and ingested during every agent briefing, Jakemon can ingest, index, and visualize telemetry across all applications using standard Grafana Alloy scrapers without a single bespoke log-parsing regex.

The Unified Decision Log (SimpleAgilityDecisionLog)

When an architectural decision affects more than one repository, it is codified in SimpleAgilityDecisionLog. Consider the ripple effect of key decisions:

  • SA-4: Established that Jakemon is the sole observability plane, preventing individual services from bundling redundant monitoring GUIs.
  • SA-7: Standardized on Pressroom as the canonical customer communication engine, initiating the deprecation of fragmented third-party hosting.
  • SA-8: Defined the spotlight flow between Stockroom and Pressroom, allowing warehouse intake operators to stage rare book discoveries as public blog drafts via API tokens.
  • SA-10: Established strict accounting boundaries between reselling inventory assets and platform infrastructure expenses.

When an agent touches code in Stockroom or Pressroom, the briefing engine ensures these system-wide rulings are present in the prompt context. An agent working on Stockroom cannot accidentally violate Pressroom's token authentication contracts because the contract is already loaded into its working memory.

Fail-Closed Engineering Invariants

Across all five repositories, Wikantik's engineering culture dictates strict defensive invariants:

  • Zero Empty Catches: A check that could not run is a check that failed. No catch block may swallow an exception or merely log a warning in a validation decision path. Code must fail closed.
  • No Unpinned Dependencies: Docker images, Maven parent POMs, and base operating systems must be pinned to explicit release digests or LTS tags. Using :latest is strictly forbidden across all compose manifests.
  • Zero Static Service Locators: Dependency injection must be clean, constructor-based, and lazy where necessary. Global static factories (like the retired WebloggerFactory in Roller) are prohibited by static analysis tests in CI.

4. Empirical Evolution: The Pruning of the Knowledge Graph

The dogfood loop is not merely a theoretical framework; it actively drives the technical evolution of Wikantik itself. The clearest demonstration of this was the permanent removal of Wikantik's Knowledge Graph in October 2026.

Earlier that year, the team invested heavily in an automated LLM entity extraction pipeline, creating 15 dedicated PostgreSQL tables, SHACL ontology validation rules, and background extraction workers. The hypothesis was that building an RDF-style entity graph would dramatically improve retrieval quality for agents executing multi-hop queries.

Because our agents used Wikantik daily to build Pressroom and Stockroom, we had a living benchmark of retrieval performance. What did the production metrics show?

  • Ingestion latency ballooned by more than 800% (from ~350ms to over 4 seconds per page).
  • Background extraction queues backed up for hours during batch imports.
  • Most damingly, systematic evaluations on our eval/retrieval testbed revealed that activating Knowledge Graph traversal reduced Mean Reciprocal Rank (MRR) from 0.842 down to 0.818. Spurious entity edges introduced irrelevant chunks that diluted context density.

Because Wikantik's users are the very agents building the platform, there was no organizational inertia defending a failed feature. In releases 2.5.12 through 2.5.14, we clobbered the subsystem: dropping 15 tables, deleting 70,500 lines of Java and TypeScript, and refocusing retrieval entirely on dense pgvector embeddings and deterministic Page Graph link structures.

The Cybernetic Future: Software That Builds Itself

The conventional paradigm of software development—human architects writing static Jira tickets for human developers who glance at outdated Confluence wikis—is collapsing under the weight of its own coordination latency. But the answer is not to replace human developers with chaotic, unconstrained LLMs that churn out undocumented code in a vacuum.

The Simple Agility model points toward a far more resilient future: the living knowledge architecture. By treating the wiki as the single source of truth for architectural contracts, deriving session context dynamically from explicit citations, enforcing fail-closed quality gates, and closing the feedback loop through continuous daily dogfooding, a single human engineer and a fleet of autonomous agents can build, maintain, and evolve an entire multi-product ecosystem with unmatched velocity and institutional coherence.

Requirements enter through the wiki; verified code exits into production; and the ecosystem grows stronger with every loop.

Authoritative Outbound References

Keep reading

Comments