Documentation Library
Architecture, decisions, runbooks, and skills
This page is generated from repository source files at build time, so the Pages site remains aligned with the docs agents are using.
Documentation
20 files- Expanded Forensic Plunkett SEO Report Decisions decisions/forensic-plunkett-seo-report.md Expanded Forensic Plunkett SEO Report Decisions Goal Complete the expanded internal forensic SEO report for Plunkett hosted Team Agent execution. Current Baseline - Asana tasks assigned to Jessie in Jessie Intake can trigger hosted Team Agent execution. - Plun
- Google Ads Reporting Channel Skill decisions/google-ads-reporting-skill.md Google Ads Reporting Channel Skill Status Started 2026-05-20. Decision Create a reusable Agency OS channel skill for Google Ads reporting, separate from the SEO reporting and technical SEO audit skills. The first implementation slice is reporting-only: - Defin
- Clean Agency OS Repository docs/adr/0001-clean-agency-os-repository.md Clean Agency OS Repository The Agency Operating System will be implemented in a new clean repository rather than by incrementally extending the current AIOps repository. The current repo is useful research for ingestion, reporting, JWH context, and early agent
- ADR 0002: Hosted Platform Build Loop Control Plane docs/adr/0002-hosted-platform-build-loop-control-plane.md ADR 0002: Hosted Platform Build Loop Control Plane Date: 2026-05-15 Status: Accepted, corrected 2026-05-18 Context The first Platform Build Loop MVP is local and operator-driven. It can validate the Asana board, assess task readiness, post Delegation Confirmat
- ADR 0003: Hosted Team Agent Work Intake docs/adr/0003-hosted-team-agent-work-intake.md ADR 0003: Hosted Team Agent Work Intake Date: 2026-05-18 Status: Accepted Context Team Agent Work is the staff-facing loop where consultants delegate client delivery work through Asana. The local MVP can assess an Asana task, check agent eligibility, post a De
- ADR 0004: Hosted Team Agent Execution MVP docs/adr/0004-hosted-team-agent-execution.md ADR 0004: Hosted Team Agent Execution MVP Date: 2026-05-18 Status: Accepted Context Hosted Team Agent intake can now notice Jessie Intake tasks, verify Jessie assignment, create a D1 Team Agent Run, assess readiness, and post a Delegation Confirmation. That pr
- ADR 0005: Live Plunkett SEO Data Snapshot MVP docs/adr/0005-live-plunkett-seo-data-snapshot.md ADR 0005: Live Plunkett SEO Data Snapshot MVP Date: 2026-05-19 Status: Accepted Context Hosted Team Agent execution could produce a review-ready Plunkett SEO artifact from a synthetic fixture. To make the review materially useful, the runner needs to fetch rea
- ADR 0006: Cloudflare Client Data Plane docs/adr/0006-cloudflare-client-data-plane.md ADR 0006: Cloudflare Client Data Plane Date: 2026-05-19 Status: Accepted Context Agency OS needs a data and presentation foundation for client onboarding, source configuration, ingestion, dashboards, future reporting, future alerts, and agent access to trusted
- Agency OS Macro Architecture Proposal docs/agency-os-macro-architecture-proposal.html Agency OS Macro Architecture Proposal Living Online Agency OS Macro architecture proposal A plain-language proposal for the first useful Agency OS: staff allocate work in Asana, agents discuss the task, agents use client context and current data, and humans ap
- Agency OS Session Context - 18 May 2026 docs/agency-os-session-context-2026-05-18.md Agency OS Session Context - 18 May 2026 This note captures the working context from the architecture discussion so a restarted Codex session can pick up without re-litigating the same decisions. Session Intent Stuart is building Agency OS for Living Online. Th
- Platform Build Loop MVP docs/architecture/platform-build-loop-mvp.md Platform Build Loop MVP Purpose The Platform Build Loop is the governed operating loop for changing the Agency Operating System itself. It turns Asana Platform Build Tasks into bounded builder-agent work, review artifacts, and human merge decisions. This MVP p
- Client Data Plane Build Blueprint docs/client-data-plane-build-blueprint.md Client Data Plane Build Blueprint Status: draft implementation blueprint Updated: 2026-05-19 Objective Build the first Cloudflare-first Client Data Plane tracer bullet for Agency OS. The first build should prove that Agency OS can onboard a brand/subscription,
- Client Data Plane Specification docs/client-data-plane-specification.md Client Data Plane Specification Status: draft for review Updated: 2026-05-19 Purpose The Client Data Plane is the Cloudflare-first subsystem that stores client onboarding configuration, source bindings, ingestion runs, normalized facts, freshness state, and da
- Client Performance Dashboard Architecture Proposal docs/client-facing-dashboard-architecture-proposal.html Client Performance Dashboard Architecture Proposal Agency OS Client Performance Client Performance Dashboard architecture proposal A proposal for an always-on staff-only Client Performance Dashboard preview that shows daily refreshed performance facts, approve
- Platform Build Loop Architecture Overview docs/platform-build-loop-architecture-overview.html Platform Build Loop Architecture Overview Living Online Agency OS Platform Build Loop architecture recap We are building the operating loop that lets Stuart and consultants manage the build of Agency OS from Asana, while Cloudflare coordinates the hosted contr
- Plunkett SEO Reporting Agent Skill Proposal docs/plunkett-seo-reporting-agent-skill-proposal.html Plunkett SEO Reporting Agent Skill Proposal Agency OS Agent Skill Proposal Plunkett SEO reporting agent A first practical Agent Skill for one JWH brand and one channel: review SEO performance, explain what changed, recommend next actions, and write useful cont
- Google Ads Reporting Skill Runbook docs/runbooks/google-ads-reporting-skill.md Google Ads Reporting Skill Runbook Purpose The Google Ads reporting skill prepares an internal consultant-facing paid search report from approved context and a dated Google Ads data snapshot. The first slice is deterministic and review-required. It does not ch
- Platform Build Loop Operator Runbook docs/runbooks/platform-build-loop-operator-runbook.md Platform Build Loop Operator Runbook Purpose This runbook describes how Builder Agents and human Admin Reviewers use the Platform Build Loop MVP to turn Asana Platform Build Tasks into checked implementation branches, Build Review Artifacts, and explicit human
- Plunkett SEO Reporting Skill Runbook docs/runbooks/plunkett-seo-reporting-skill.md Plunkett SEO Reporting Skill Runbook Purpose The Plunkett SEO Reporting Skill is the first Agency OS client delivery agent component. It turns an Asana reporting request, an approved client context pack, and a dated SEO data snapshot into a consultant-facing r
- Team Agent Work Intake Runbook docs/runbooks/team-agent-work-intake.md Team Agent Work Intake Runbook Purpose Team Agent Work is the first live path for staff to delegate delivery work through Asana. The local MVP lets an operator point the agent at an Asana task, verify that it is agent-eligible, post a Delegation Confirmation,
Agent Skills
38 files- SKILL .agents/skills/caveman/SKILL.md --- name: caveman description: Ultra-compressed communication mode. Cuts token usage ~75% by dropping filler, articles, and pleasantries while keeping full technical accuracy. Use when user says "caveman mode", "talk like caveman", "use caveman", "less tokens"
- Diagnose .agents/skills/diagnose/SKILL.md --- name: diagnose description: Disciplined diagnosis loop for hard bugs and performance regressions. Reproduce → minimise → hypothesise → instrument → fix → regression-test. Use when user says "diagnose this" / "debug this", reports a bug, says something is b
- SKILL .agents/skills/grill-me/SKILL.md --- name: grill-me description: Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill m
- ADR Format .agents/skills/grill-with-docs/ADR-FORMAT.md 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 That's it. An ADR can be a single paragraph. The value is in recording that a
- CONTEXT.md Format .agents/skills/grill-with-docs/CONTEXT-FORMAT.md CONTEXT.md Format Structure Rules - Be opinionated. When multiple words exist for the same concept, pick the best one and list the others as aliases to avoid. - Flag conflicts explicitly. If a term is used ambiguously, call it out in "Flagged ambiguities" with
- SKILL .agents/skills/grill-with-docs/SKILL.md --- name: grill-with-docs description: Grilling session that challenges your plan against the existing domain model, sharpens terminology, and updates documentation CONTEXT.md, ADRs inline as decisions crystallise. Use when user wants to stress-test a plan aga
- SKILL .agents/skills/handoff/SKILL.md --- name: handoff description: Compact the current conversation into a handoff document for another agent to pick up. argument-hint: "What will the next session be used for?" --- Write a handoff document summarising the current conversation so a fresh agent ca
- Deepening .agents/skills/improve-codebase-architecture/DEEPENING.md Deepening How to deepen a cluster of shallow modules safely, given its dependencies. Assumes the vocabulary in LANGUAGE.md LANGUAGE.md — module , interface , seam , adapter . Dependency categories When assessing a candidate for deepening, classify its dependen
- Interface Design .agents/skills/improve-codebase-architecture/INTERFACE-DESIGN.md Interface Design When the user wants to explore alternative interfaces for a chosen deepening candidate, use this parallel sub-agent pattern. Based on "Design It Twice" Ousterhout — your first idea is unlikely to be the best. Uses the vocabulary in LANGUAGE.md
- Language .agents/skills/improve-codebase-architecture/LANGUAGE.md Language Shared vocabulary for every suggestion this skill makes. Use these terms exactly — don't substitute "component," "service," "API," or "boundary." Consistent language is the whole point. Terms Module Anything with an interface and an implementation. De
- Improve Codebase Architecture .agents/skills/improve-codebase-architecture/SKILL.md --- 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, cons
- Logic Prototype .agents/skills/prototype/LOGIC.md Logic Prototype A tiny interactive terminal app that lets the user drive a state model by hand. Use this when the question is about business logic, state transitions, or data shape — the kind of thing that looks reasonable on paper but only feels wrong once yo
- Prototype .agents/skills/prototype/SKILL.md --- name: prototype description: Build a throwaway prototype to flesh out a design before committing to it. Routes between two branches — a runnable terminal app for state/business-logic questions, or several radically different UI variations toggleable from o
- UI Prototype .agents/skills/prototype/UI.md UI Prototype Generate several radically different UI variations on a single route, switchable from a floating bottom bar. The user flips between variants in the browser, picks one or steals bits from each , then throws the rest away. If the question is about l
- Domain Docs .agents/skills/setup-matt-pocock-skills/domain.md Domain Docs How the engineering skills should consume this repo's domain documentation when exploring the codebase. Before exploring, read these - CONTEXT.md at the repo root, or - CONTEXT-MAP.md at the repo root if it exists — it points at one CONTEXT.md per
- Issue tracker: GitHub .agents/skills/setup-matt-pocock-skills/issue-tracker-github.md Issue tracker: GitHub Issues and PRDs for this repo live as GitHub issues. Use the gh CLI for all operations. Conventions - Create an issue : gh issue create --title "..." --body "..." . Use a heredoc for multi-line bodies. - Read an issue : gh issue view --co
- Issue tracker: GitLab .agents/skills/setup-matt-pocock-skills/issue-tracker-gitlab.md Issue tracker: GitLab Issues and PRDs for this repo live as GitLab issues. Use the glab https://gitlab.com/gitlab-org/cli CLI for all operations. Conventions - Create an issue : glab issue create --title "..." --description "..." . Use a heredoc for multi-line
- Issue tracker: Local Markdown .agents/skills/setup-matt-pocock-skills/issue-tracker-local.md Issue tracker: Local Markdown Issues and PRDs for this repo live as markdown files in .scratch/ . Conventions - One feature per directory: .scratch/ / - The PRD is .scratch/ /PRD.md - Implementation issues are .scratch/ /issues/ - .md , numbered from 01 - Tria
- Setup Matt Pocock's Skills .agents/skills/setup-matt-pocock-skills/SKILL.md --- name: setup-matt-pocock-skills description: Sets up an Agent skills block in AGENTS.md/CLAUDE.md and docs/agents/ so the engineering skills know this repo's issue tracker GitHub or local markdown , triage label vocabulary, and domain doc layout. Run before
- Triage Labels .agents/skills/setup-matt-pocock-skills/triage-labels.md Triage Labels The skills speak in terms of five canonical triage roles. This file maps those roles to the actual label strings used in this repo's issue tracker. | Label in mattpocock/skills | Label in our tracker | Meaning | | -------------------------- | ---
- Deep Modules .agents/skills/tdd/deep-modules.md Deep Modules From "A Philosophy of Software Design": Deep module = small interface + lots of implementation Shallow module = large interface + little implementation avoid When designing interfaces, ask: - Can I reduce the number of methods? - Can I simplify th
- Interface Design for Testability .agents/skills/tdd/interface-design.md Interface Design for Testability Good interfaces make testing natural: 1. Accept dependencies, don't create them 2. Return results, don't produce side effects 3. Small surface area - Fewer methods = fewer tests needed - Fewer params = simpler test setup
- When to Mock .agents/skills/tdd/mocking.md When to Mock Mock at system boundaries only: - External APIs payment, email, etc. - Databases sometimes - prefer test DB - Time/randomness - File system sometimes Don't mock: - Your own classes/modules - Internal collaborators - Anything you control Designing
- Refactor Candidates .agents/skills/tdd/refactoring.md Refactor Candidates After TDD cycle, look for: - Duplication → Extract function/class - Long methods → Break into private helpers keep tests on public interface - Shallow modules → Combine or deepen - Feature envy → Move logic to where data lives - Primitive o
- Test-Driven Development .agents/skills/tdd/SKILL.md --- name: tdd description: Test-driven development with red-green-refactor loop. Use when user wants to build features or fix bugs using TDD, mentions "red-green-refactor", wants integration tests, or asks for test-first development. --- Test-Driven Developmen
- Good and Bad Tests .agents/skills/tdd/tests.md Good and Bad Tests Good Tests Integration-style : Test through real interfaces, not mocks of internal parts. Characteristics: - Tests behavior users/callers care about - Uses public API only - Survives internal refactors - Describes WHAT, not HOW - One logical
- Technical SEO Audit Rubric .agents/skills/technical-seo-audit/references/rubric.md Technical SEO Audit Rubric Severity - Critical: blocks crawling/indexing or invalidates audit completeness across important sections. - High: likely suppresses rankings, indexability, canonical clarity, or key user/crawl paths. - Medium: measurable SEO hygiene
- Technical SEO Audit .agents/skills/technical-seo-audit/SKILL.md --- name: technical-seo-audit description: Run consultant-facing technical SEO audits from Asana-triggered public website crawl tasks. Use when a task asks for a technical SEO audit, site crawl audit, Screaming Frog-style audit, crawl/indexability/canonical re
- To Issues .agents/skills/to-issues/SKILL.md --- name: to-issues description: Break a plan, spec, or PRD into independently-grabbable issues on the project issue tracker using tracer-bullet vertical slices. Use when user wants to convert a plan into issues, create implementation tickets, or break down wo
- SKILL .agents/skills/to-prd/SKILL.md --- name: to-prd description: Turn the current conversation context into a PRD and publish it to the project issue tracker. Use when user wants to create a PRD from the current context. --- This skill takes the current conversation context and codebase underst
- Writing Agent Briefs .agents/skills/triage/AGENT-BRIEF.md Writing Agent Briefs An agent brief is a structured comment posted on a GitHub issue when it moves to ready-for-agent . It is the authoritative specification that an AFK agent will work from. The original issue body and discussion are context — the agent brief
- Out-of-Scope Knowledge Base .agents/skills/triage/OUT-OF-SCOPE.md Out-of-Scope Knowledge Base The .out-of-scope/ directory in a repo stores persistent records of rejected feature requests. It serves two purposes: 1. Institutional memory — why a feature was rejected, so the reasoning isn't lost when the issue is closed 2. Ded
- Triage .agents/skills/triage/SKILL.md --- name: triage description: Triage issues through a state machine driven by triage roles. Use when user wants to create an issue, triage issues, review incoming bugs or feature requests, prepare issues for an AFK agent, or manage issue workflow. --- Triage M
- Writing Skills .agents/skills/write-a-skill/SKILL.md --- name: write-a-skill description: Create new agent skills with proper structure, progressive disclosure, and bundled resources. Use when user wants to create, write, or build a new skill. --- Writing Skills Process 1. Gather requirements - ask user about: -
- SKILL .agents/skills/zoom-out/SKILL.md --- name: zoom-out description: Tell the agent to zoom out and give broader context or a higher-level perspective. Use when you're unfamiliar with a section of code or need to understand how it fits into the bigger picture. disable-model-invocation: true --- I
- Google Ads Reporting skills/google-ads-reporting/SKILL.md --- name: google-ads-reporting description: Agency OS Channel Skill for Google Ads reporting tasks. Use when an agent is asked to review paid search or Google Ads performance, explain spend/conversion movement, draft internal consultant reporting, recommend fo
- Plunkett SEO Pilot skills/seo-reporting/references/plunkett-pilot.md Plunkett SEO Pilot Boundary The pilot proves one Agency OS Channel Skill for one client group, one business unit, and one channel: - Client group: JWH Group. - Business unit and pilot brand: Plunkett Homes / Plunkett. - Channel: SEO. - Primary task surface: As
- SEO Reporting skills/seo-reporting/SKILL.md --- name: seo-reporting description: Agency OS Channel Skill for SEO reporting tasks. Use when an agent is asked to review SEO performance, explain organic search changes, draft consultant-facing reporting, recommend SEO follow-up work, write source-backed evi