Simple Agility Agent Coordination

The Simple Agility stack spans multiple independent repositories: jspwiki (Wikantik), stockroom, roller, blogger-agent, jakemon, and wealthview. Because development is increasingly driven by autonomous and paired coding agents (such as Antigravity agy, Claude Code, and specialized subagents), this wiki serves as the central asynchronous communication bus and authoritative architectural decision engine across all repositories.

This page defines the normative protocol coding agents must follow when planning, executing, and recording cross-repo work, and provides the live ledger of active multi-repo initiatives.

flowchart TD
    subgraph Repositories["Coding Agents in Repositories (agy / Claude Code)"]
        A1["Stockroom Agent<br/>(WMS & Intake)"]
        A2["Roller / Blogger Agent<br/>(Customer Outreach)"]
        A3["Platform Agent<br/>(Telemetry & Engine)"]
    end

    subgraph Wiki_Bus["Wikantik Coordination Hub (MCP / Knowledge Layer)"]
        DEC["SimpleAgilityDecisionLog<br/>(Binding Architectural ADRs)"]
        LEDGER["SimpleAgilityAgentCoordination<br/>(Active Initiatives Ledger)"]
        ROADMAP["SimpleAgilityRoadmap<br/>(Sequenced Backlog & State)"]
        CONTRACTS["Telemetry & Domain Contracts<br/>(ECS, Labels, Rules)"]
    end

    A1 -->|1. Sense Decisions & Contracts| DEC
    A2 -->|1. Sense Decisions & Contracts| DEC
    A3 -->|1. Sense Decisions & Contracts| DEC

    A1 -->|2. Register Active Task| LEDGER
    A2 -->|2. Register Active Task| LEDGER
    A3 -->|2. Register Active Task| LEDGER

    A1 -->|3. Check Boundaries| CONTRACTS
    A2 -->|3. Check Boundaries| CONTRACTS
    A3 -->|3. Check Boundaries| CONTRACTS

    A1 -->|4. Update State on Completion| ROADMAP
    A2 -->|4. Update State on Completion| ROADMAP
    A3 -->|4. Update State on Completion| ROADMAP

1. The Coding Agent Contract

Every coding agent operating within any Simple Agility repository must observe four mandatory rules:

Rule 1: Sense Before Acting

Start the session with get_briefing(clusters=["<project cluster>"], prompt="<your first task>") on the Wikantik knowledge MCP. It returns the project's own pages and every shared page the project cites, so most of the reading below arrives in one call (SA-13). Before proposing or making changes that span product boundaries (e.g. logging formats, database schemas, inter-process communication, or API endpoints), an agent must query Wikantik via MCP (read_pages, retrieve_context) to read:

1. SimpleAgilityStackHub — Product ownership boundaries and the core ownership principle.
2. SimpleAgilityDecisionLog — Binding dated architectural decisions (SA-1 through SA-13).
3. SimpleAgilityRoadmap — What is already built versus planned.
4. This page — Current in-flight initiatives and registered agent tasks.

Rule 2: Register Active Work in the Ledger

When an agent begins a task that modifies a contract, introduces a cross-repo dependency, or fulfills an item on the roadmap, it must update the Active Initiatives Ledger below using the Wikantik Admin MCP (update_page) with optimistic locking. This prevents conflicting changes across disjoint agent sessions.

Rule 3: Contract-First Modifications

No agent may implement a cross-product change (e.g. changing an event payload between Stockroom and Roller, or altering an MDC log key) in application code before the change is reflected in the relevant contract page:

• Telemetry, metrics, or logging \to SimpleAgilityTelemetryContract
• Product loop mechanics \to SimpleAgilityFeedbackLoopPattern
• Reselling listing policies \to ResellingHub
• Inter-product decisions \to SimpleAgilityDecisionLog

When a project adopts a contract, a page in that project's cluster must link to it: a citation is how the briefing learns the project is bound by it (SA-13).

Rule 4: Record Decisions in the Decision Log

If an implementation choice establishes a precedent binding more than one repository, the agent must document it as a new numbered entry SA-XX in SimpleAgilityDecisionLog using the mandatory three-part structure: Decision, Why, and Consequences.

2. Standard Repository Agent Header

Every repository in the Simple Agility stack must carry the following instruction block at the top of its agent instruction file (CLAUDE.md and/or .agents/AGENTS.md). Agents reading this header are immediately grounded in the cross-product architecture:

<!-- SIMPLE-AGILITY-AGENT-HEADER-START -->
## Simple Agility Architectural Context
This repository is part of the **Simple Agility** small-business ecosystem:
- **Architecture Hub:** Refer to `SimpleAgilityStackHub` on Wikantik (`https://wiki.wikantik.com/SimpleAgilityStackHub`).
- **Architectural Decisions:** Consult `SimpleAgilityDecisionLog` before changing cross-repo APIs, logging, or telemetry.
- **Active Initiatives & Coordination:** Check `SimpleAgilityAgentCoordination` before starting multi-repo work.
- **Session start:** call `get_briefing(clusters=["<project cluster>"], prompt="<your first task>")` on the Wikantik knowledge MCP; the briefing carries this project's pages and the contracts it cites (`SA-13`).
- **Role Boundary:** Optimize local product logic, but never break cross-product contracts or telemetry conventions.
<!-- SIMPLE-AGILITY-AGENT-HEADER-END -->

The project clusters are wikantik-development (Wikantik), jakemon, roller and stockroom (StockroomHub).

3. Active Initiatives & Cross-Repo Work Ledger

The following ledger tracks active, queued, and completed cross-repo initiatives across the suite. Agents updating this table must preserve existing rows and record their assigned ID, touched repositories, and verifiable acceptance state.

4. Agent Tooling & Verification Protocols

When an agent needs to read or modify wiki architecture artifacts:

• Reading Contracts: Use Knowledge MCP read_pages or retrieve_context. Anonymous HTTP GET https://wiki.wikantik.com/api/pages/{slug} is available for non-agent services (like Stockroom).
• Updating Contracts: Always use Admin MCP update_page passing expectedContentHash to ensure atomic updates. If expectedContentHash mismatches, re-read the page and merge changes cleanly.
• Creating Runbooks & Specs: Use Admin MCP write_pages with strictly valid YAML frontmatter (summary between 50 and 160 characters, lowercase kebab-case tags, escaped currency symbols \$).
• Verifying Compliance: Run bin/simple-agility-conformance.sh in the Wikantik repository to machine-check health, metrics endpoints, and ECS log compliance.

See Also

• SimpleAgilityStackHub — Ecosystem overview, component roles, and data backbone principles.
• SimpleAgilityDecisionLog — Dated, binding architectural decisions (SA-1 through SA-13).
• SimpleAgilityRoadmap — Sequenced implementation backlog and acceptance milestones.
• SimpleAgilityTelemetryContract — Concrete metrics, logging, and health specifications.
• ProjectContextSeparationDesign — How the session-start briefing derives a project's pages and the contracts it cites (SA-13).
• RollerHub — Customer communication architecture, weblogs, and agent MCP integration.
• ResellingHub — Business rules and style guides for inventory listing preparation.