How a Gillish plugin gets built.

Why this is written down#

Gillish is a one-person studio that builds WordPress plugins with an AI coding agent. The risk of that setup is not speed; it is drift. An agent that improvises a different process every session produces inconsistent work, and a solo maintainer cannot catch every inconsistency by hand. The defence is a written process that every session loads and follows, so the work stays coherent across sessions and across tools.

This page describes that process so a collaborator, a reviewer, a future maintainer, or the agent itself, opening a fresh session on a future plugin, can see exactly how a feature moves from idea to shipped code, and can push back on any step. Nothing here is secret. Credentials, keys, and deploy mechanics that depend on secrets are deliberately excluded; this is about the method, not the machinery.

The method is shared across every Gillish plugin. Per-plugin CLAUDE.md files extend or refine it; this page is the abstract bar that every plugin's instructions inherit. When a plugin file and this page disagree, the plugin file wins for that plugin and a note explains why.

1: The coding doctrine#

Every project inherits four principles. They exist because LLM-driven coding has known failure modes, and each principle names one of them and the discipline that prevents it. The principles are loaded automatically from the agent's user-global CLAUDE.md, and surface as an explicit skill the agent can invoke (andrej-karpathy-skills:karpathy-guidelines) whenever the doctrine itself needs to be re-asserted.

The doctrine is the abstract bar. Each project's own CLAUDE.md defines the concrete checks and the concrete edits not to make, and the project file wins where the two overlap. The doctrine does not get re-litigated per task; it is the floor.

2: The skills layer#

On top of the doctrine sit skills: named, loadable procedures the agent runs explicitly rather than improvising. Each is invoked by name (/<skill> or via the agent's Skill tool); each carries its own loading instructions, refuses to proceed without required context, and has a defined output. The rule is structural: if a task has a skill, the skill runs; the agent does not freestyle the equivalent.

2.1 impeccable: design & UX#

The central skill for production-grade interface work. Every UI task, from a new block to a new inspector panel to a docs page on this site, is invoked as one of impeccable's commands, never as a freeform "go design something". Before any command touches a file, the skill loads the project's product brief and design context and refuses to proceed without it. It then classifies the surface as either a brand register (the design is the product, like this docs site) or a product register (the design serves a task, like a plugin's inspector panel), and applies a different bar to each.

The commands fall into four families:

The shared design laws apply to both registers: a committed colour strategy; light or dark chosen from a concrete usage scene rather than by reflex; restrained accent; and a list of absolute bans (gradient text, decorative glassmorphism, side-stripe borders, the hero-metric template, identical card grids, modal-as-first-thought). A critique or audit pass fails any surface that breaks a ban.

2.2 mobbin-ui-research#

Any net-new visual surface, a new block, a new inspector panel, an admin page, an empty or error state, a docs page that introduces a new layout, runs a mobbin-ui-research session before the design brief is written. It is a required step, not a suggestion: impeccable shape blocks on the research note's existence for surfaces that need one.

The skill drives the Mobbin MCP server (mcp__mobbin__search_screens) to translate the design goal into concrete screen descriptions, pull real product screenshots, and synthesise what mature tools actually do for the same problem. The output is a research note in the decision vault citing each screen used. Polish passes and copy-only changes skip it.

2.3 The WordPress skill family#

WordPress-specific work routes through a family of skills, each scoped to one part of the platform. The router skill wordpress-router classifies the repository on session entry (plugin, theme, block theme, WP-core checkout, Gutenberg) and routes to the right narrower skill.

2.4 Verification skills#

Verification is its own family of skills, kept separate from build skills so the "is this actually done?" gate does not get folded into the work that created it.

2.5 Obsidian decision-log skills#

The decision vault (see section 8) is operated through three skills:

2.6 Process & harness skills#

A small set of skills configure how the agent operates rather than what it produces:

• anthropic-skills:skill-creator: authoring new skills, modifying or improving existing ones, running evals to test a skill, benchmarking with variance analysis, optimising a skill's description for better triggering accuracy. Runs whenever the method itself is changed.
• anthropic-skills:consolidate-memory: reflective pass over the agent's memory files: merge duplicates, fix stale facts, prune the index. Runs periodically and after major ecosystem shifts (floor-lift batches, new plugin added, new MCP server adopted).
• find-skills: the meta-skill for discovering and installing additional skills when a task needs functionality that may already exist as a skill.
• update-config: configures the agent's harness via settings.json (hooks, permissions, env vars). Used when a recurring behaviour needs to be automated at the harness layer rather than asked-for per session.
• fewer-permission-prompts: scans session transcripts for common read-only commands and adds them to the project's permission allowlist. Reduces ceremony without lowering the security bar.
• loop: recurring task on an interval ("check the deploy every 5 minutes", "keep watching this PR"). Used for poll-until-done patterns and ambient watching.
• schedule: remote scheduled agents on a cron expression. The escalation from loop when the recurring work should outlive the current session.
• claude-api: building, debugging, and optimising Claude API / Anthropic SDK applications. Runs whenever a Gillish plugin gains an Anthropic-SDK code path (e.g. MCP's eventual server-side ability hooks).
• defuddle: extract clean markdown from web pages, removing clutter. The agent uses this in place of raw WebFetch for any non-.md URL when researching docs, articles, or vendor pages.
• keybindings-help: a minor harness utility used when the operator's keyboard shortcuts need to be configured.
• coding-guidelines: the Karpathy-derived behavioural rules (state assumptions, surgical changes, minimum diff, root-cause-not-symptom) that turn the §1 doctrine from a stated bar into an in-line constraint on every edit. Active on every coding turn; shipped upstream as andrej-karpathy-skills:karpathy-guidelines.
• gh-address-comments: addresses review and issue comments on the current branch's open PR via the gh CLI. Runs after a code-review pass produces actionable feedback, or when the operator asks for PR comments to be handled.
• brightdata-plugin:bright-data-mcp: the skill-side driver for the Bright Data MCP server listed in §3. Runs whenever public web data needs to enter the workflow (competitor wp.org listings, search-result extraction, structured scraping). Manages query shaping, result parsing, and the MCP connection lifecycle so raw server calls don't surface in the agent's working context.

2.7 Docs-site & SEO skills#

The html.gillish.com docs site is its own repo with its own skill family. The studio's posture is that docs pages are working artefacts, not marketing pages, but SEO and content discipline still apply to them.

• searchfit-seo:seo-audit: comprehensive audit of the docs site or a single page (titles, meta, headings, structured data, internal linking).
• searchfit-seo:on-page-seo, technical-seo, schema-markup, internal-linking, broken-links: narrower passes; the agent reaches for the right one based on the audit finding.
• searchfit-seo:content-strategy, content-brief, keyword-clustering, create-topic, create-content: when a new docs page or section is being planned, not just iterated.
• searchfit-seo:ai-visibility: AI-Overview / AI-answer optimisation: how a page is read by search-grade LLMs (Google AI Overviews, Perplexity, ChatGPT browsing), what gets quoted, what gets attributed. Runs alongside the SEO audit when a page's audience includes "an AI agent summarising the studio for someone else", increasingly the path users find docs pages by.
• marketing:brand-review: brand-voice / style-guide review of a draft. Used as the final pass on any new top-level docs page (this one included).
• marketing:draft-content, content-creation: when an SEO-shaped draft is the desired output rather than a single edit.

Anthropic's file-format skills, anthropic-skills:pdf, docx, pptx, xlsx, sit alongside but are invoked only when a non-HTML artefact (a CRA-compliance brief in .docx, a SBOM viewer in .xlsx) is the deliverable.

2.8 Design-prototyping skills#

The design loop pulls five skills, split between pre-shape research (finding the right direction before the brief locks) and in-craft iteration (tightening the chosen direction once code is moving). The two pre-shape skills sit alongside impeccable shape:

• mobbin-ui-research: covered in §2.2; the "what do mature products do for this problem" surface, mandatory before any net-new visual surface earns its shape brief.
• anthropic-skills:web-artifacts-builder: rapid in-chat prototyping using React + Tailwind + shadcn/ui. The "what would our concept actually look like" surface. Materialises two or three layout-direction candidates as live HTML artifacts the operator can review before the brief locks. Not a production-code tool, Cairnstone's blocks live in @wordpress/element (WP's React), not shadcn. Artifacts are ephemeral chat scaffolds for direction-finding, never shipped code.

Typical sequence in a heavy-path entry: load context → mobbin-ui-research (understand the convention) → web-artifacts-builder (explore concrete candidates) → impeccable shape (lock the chosen direction in a brief). The middle step is optional but cheap; one artifact session saves a round of shape-brief revision when the chosen direction is contested.

The three in-craft iteration skills come into play after the brief locks, when the question shifts from "what is the right pattern" to "is this rendering the way the brief said it should":

• chrome-devtools: DOM inspection, console-log capture, network-request timing, and performance profiling against a running page. Sits alongside Chrome MCP in the iterative craft loop: Chrome MCP drives the surface check, chrome-devtools opens the inspector underneath when the check finds something to debug.
• playwright-skill: scripted browser flows in real Chromium / WebKit / Firefox. Used when a one-shot verification needs to become a repeatable artifact, e.g. when the same regression keeps surfacing across light/dark mode or across the three local Studio sites and the check earns its place as a recorded script. Not the default; reach for it when Chrome MCP one-shots are no longer enough.
• web-quality-audit: multi-axis audit (accessibility + performance + best-practices) of a live page or component. Sits between impeccable audit (design quality) and §2.10's accessibility (WCAG methodology): broader than the pure-WCAG manual review, narrower than composer verify:deep. Runs as a craft-loop fast-feedback pass before any heavy-path UI surface is declared shippable.

2.9 Performance measurement#

Four skills cover the perf surface, split between live-environment measurement (the "is this slow, and from where" question) and frontend-quality auditing (the "what should we optimise" question). None of them sit on the push-gate critical path, perf work is operator-invoked, not per-push gated.

• global-speed-checker: runs HTTP timing checks against any endpoint from multiple regions worldwide. Used to baseline a published frontend before launch, to debug a "Cairnstone feels slow" report by isolating which region degraded, and to capture Phase-N before/after measurements when a heavy-path change affects rendering. Too slow and too sensitive to network flake to sit on the push-gate critical path; reserved for pre-launch baselines, post-major-change audits, and ad-hoc debug. CRA Annex I row (2)(h) "Availability + DoS mitigation" becomes load-bearing the moment Cairnstone hits the wp.org launch; global perf measurement is the evidence trail.
• perf-lighthouse: full Lighthouse audit (performance + best-practices + SEO + a11y subscore) against a URL. Runs as a one-shot quality bar before a top-level docs page or a Cairnstone admin surface is declared done, and on demand when a regression report needs a structured second opinion. Complementary to §2.10's accessibility skill (Lighthouse catches the automatable a11y axis; the accessibility skill grounds the manual review).
• core-web-vitals: the three Google-tracked metrics specifically: Largest Contentful Paint, Interaction to Next Paint, Cumulative Layout Shift. Narrow scope: when a docs page or Cairnstone surface has a known CWV regression and the work is to land the specific fix (image preloading, hydration deferral, layout stabilisation). The skill that runs when the question is "the CWV number is bad, what specifically to change".
• perf-web-optimization: broader web-perf guidance: bundle size, image strategy, caching headers, render-blocking resources, JS execution cost. Sits one level out from core-web-vitals; runs when a surface needs a perf pass that isn't yet narrowed to a single failing metric.

2.10 Accessibility audit#

One skill provides WCAG-grounded patterns and review methodology for accessibility work, invoked alongside impeccable audit when a heavy-path UI surface needs a11y verification, and as a standing pattern reference during craft on any user-facing component.

• accessibility (from addyosmani/web-quality-skills, installed 2026-05-22), provides the WCAG POUR framework (Perceivable / Operable / Understandable / Robust), conformance levels (A / AA / AAA), and pattern catalogue for text alternatives, ARIA roles, keyboard navigation, focus management, colour contrast, and the screen-reader / assistive-tech expectations every Cairnstone / Node / Core admin surface must meet. What it IS: methodology + pattern reference loaded into agent context during a11y work. What it is NOT: an automated DOM scanner, it does not invoke axe-core / pa11y / lighthouse-a11y; it grounds the manual review the agent performs.

Scope note, WCAG 2.1 vs 2.2. The skill targets WCAG 2.1 AA. The studio's declared bar in §13 + the per-tool security pages is WCAG 2.2 AA. Of the nine criteria 2.2 added on top of 2.1, three are catchable by axe-core's modern ruleset (Target Size 2.5.8, Focus Appearance 2.4.13, Focus Not Obscured Minimum 2.4.11) when an axe-based automation is wired in. The remaining six (Focus Not Obscured Enhanced, Dragging Movements, Consistent Help, Redundant Entry, Accessible Authentication Min/Enh) require manual checklist review during impeccable audit. The accessibility skill grounds that manual review; it does not by itself certify 2.2 AA.

Still an open gap: automated a11y scanning. No skill in the current stack invokes axe-core, pa11y, or lighthouse-a11y against a live URL or DOM snapshot. The accessibility skill closes the methodology gap; the automation gap remains as a future Layer-6 candidate in the verification stack, most likely deferred until Cairnstone has a stable launch-ready admin surface to baseline against.

3: The MCP-server inventory#

The agent's verification and introspection power comes from a fixed inventory of MCP servers (Model Context Protocol). Each server is named, each has a defined role, and the agent picks based on what the task actually needs, not by reflex.

Picking the right tier matters. Each MCP server trades coverage against speed and precision. The fixed rule: start at the most specific tool that can answer the question. A dedicated app MCP beats Chrome MCP, which beats Computer-use MCP. A wrong-tier choice usually means the agent is about to click pixels at something Chrome MCP could read from the DOM.

The fallback ladder when a server is down. The verify skill primarily drives Chrome MCP for any web-UI surface check. If Chrome MCP is unavailable mid-session, the fallback ladder is:

1. For server-side state verification (option values, plugin active state, ability registration, post-meta, transients): use WP-CLI via the wp-wpcli-and-ops skill, a direct database read, or a focused Chrome MCP admin-page probe against the target Studio site. These give server-side ground truth without a remote adapter.
2. For desktop / native-app surfaces (Obsidian, Finder, system settings): use Computer-use MCP at the appropriate tier (browsers get the read tier; IDEs get click; native apps get full). Not relevant for plugin verification; only for operator-environment work.
3. If no MCP path reaches the surface in question: surface the gap explicitly in chat and stop. A failed verify is reportable; it is never optional and never silently skipped. The Karpathy "Goal-Driven Execution" principle in §1 names this, diagnose, do not suppress.

What this is NOT: the fallback ladder is not a degraded-mode default. Chrome MCP is the right tool for web-UI verification; the ladder is for actual outage handling, not for opportunistically skipping browser checks.

3.5: The three speeds: fast / feature / heavy#

Not every task earns the full ceremony. A gearbox at the top of every session selects between three speeds, sized to the scope of what is actually being changed. The gearbox is enforced structurally: before any code or file edit, the agent outputs an initialisation block declaring the mode, the task in one sentence, the target files, the explicit "done means" criterion, and a one-line justification for the chosen speed.

The pipeline described in §4 (the shape → craft → audit → polish sequence) and the phase-based pattern in §5 are heavy-path territory. feature-path uses a 3-line implementation plan and skips Mobbin research and shape briefs. fast-path skips both the plan and the pipeline, execution is the verification.

The Obsidian decision log in §8 inherits the same gating: a note is required only when a change crosses one of four explicit thresholds (schema lock-in, new pluggable engine, cross-plugin behaviour change, platform floor lift). For routine helpers and standard settings fields, the vault stays clean.

Every turn, no exceptions. The initialisation block is not optional, not "for big changes only", not skippable when the next edit feels obvious. Every turn that touches code or files starts with the Mode Selection Grid, if a turn does not need an edit, the grid is skipped; the moment an edit is on the table, the grid precedes it. The discipline exists because the dominant failure mode of agent-driven coding is the agent that "just" makes a small edit and snowballs from there without ever declaring what "done" looks like. The grid is the structural answer.

Session-start acknowledgement. On the first turn of a new session, the agent acknowledges the loaded method by listing the current platform minimums (WordPress and PHP, see §3.6) and standing by for the first task. From that point on, every turn that touches code or files starts with the Mode Selection Grid. This is the one mandated agent output that is not a Mode Grid, everything after it on a coding turn is.

Per-plugin CLAUDE.md loader directives sit at the top of each plugin's manifest file and point at this method page as the read-first source on session entry. Per-plugin manifests carry deviations from this baseline; this page is the abstract bar every plugin's manifest inherits.

3.6: The runtime baseline & security boundary#

Every Gillish plugin codes for a modern runtime baseline: WordPress 6.9+ and PHP 8.3+. Tested up to WordPress 7.0 / PHP 8.5 on the bleeding Studio site. The floor is part of the plugin's declared interface; a floor-lift is treated under the discipline in §9.

• Input sanitisation + validation are mandatory at every entry point. Output escaping (esc_html, esc_attr, esc_url, wp_json_encode, wp_kses_post) happens at the exact render boundary, not earlier.
• Privilege checking. All administrative entry points, AJAX callbacks, and REST routes explicitly enforce capability checks (current_user_can( 'manage_options' ) or the appropriate granular capability) and verify nonces (wp_verify_nonce / check_ajax_referer / permission_callback). Never weaken a security boundary to make a quick test pass.
• PHP 8.3 optimisation. Use Typed Class Constants (public const string SLUG = '...'), explicit type hints on every parameter and return, declare( strict_types=1 ); at the top of every PHP file in src/, strict comparison operators (=== / !==), and json_validate() when validating JSON strings before json_decode.
• No .env, no hardcoded secrets. Configuration lives in wp-config.php constants, WP options, or each plugin's typed Shared\Options constants. No credential, key, or token in any tracked file.
• No server-level config from plugin code. Strict CSP, TLS headers, HSTS belong to the host/server layer, not the plugin. A plugin that emits them breaks core and Gutenberg.
• WordPress owns the password store. Never override or mirror wp_hash_password / phpass / bcrypt.

Compliance with the broader GDPR / CCPA / CRA / OWASP / WCAG 2.2 AA posture is handled as guardrails, see §13. The rules above are the per-edit security floor; the guardrails are the program-level commitments.

3.7: Session length & context discipline#

The 1M-token context window does not mean unlimited useful context. Retrieval degrades the more unrelated content sits in working memory, "lost in the middle" is a real failure mode even at high token counts. Three rules keep this in check:

1. The Files: list in the init block is normative. Files outside it are not read this turn unless the agent surfaces an explicit need and updates the init block in the next turn. No speculative tree-walking just because the window has room.
2. Checkpoint at ~250–300k tokens, then /clear. Long heavy-path sessions that pass that threshold land a checkpoint to .claude/active-state.md in the working plugin repo before clearing, what's done, what's next, where the reasoning is paused, the exact slash-command to invoke on resume. The cross-session surfaces (vault 00 <Tool> Index.md Current state dashboard, Z:\Dev\Obsidian\<Plugin>\Plans\DONE-WORK.md, the agent's auto-memory) already handle long-term continuity; the active-state file handles only in-flight task continuity during a single multi-day work thread.
3. Delegate deep exploration to read-only subagents. When heavy-path needs to scan multiple plugin repos, audit a 1000+ line module, or do a cross-vault grep before committing to a shape, use the Explore or general-purpose Agent tool. The subagent reads broadly, writes a focused markdown report to disk (Z:\Dev\Obsidian\<Plugin>\Plans\<topic>-research.md for plan-adjacent work, Z:\Dev\Obsidian\<Tool>\Research\ for strategic reasoning that should land in the Obsidian vault), and the main agent reads back in. Preserves the main agent's context budget for synthesis and edits. Plan-only subagents (the Plan agent type) are the same pattern for design-decision exploration.

4: The pipeline, step by step#

This sequence is the heavy-path expansion (see §3.5 for when each speed applies). feature-path uses a 3-line implementation plan in place of Shape, skips Research, and otherwise follows Craft → Evaluate → Verify → Decision log only if §8 triggers. fast-path skips the pipeline entirely, execution is the verification.

A heavy-path feature moves through the same sequence every time. Each step has an output the next step depends on, and a named skill that owns it.

Steps are not compressed. Shape confirmation is not a licence to skip straight to building; it is permission to begin the next gate. The dominant failure mode of this kind of pipeline is collapsing the gates because an earlier one felt complete, so the gates are kept distinct on purpose.

The work is built in passes and committed in small, reviewable units, each with its own focused message and its verification result recorded in the commit. A reviewer can follow the history one decision at a time rather than reading one large diff.

5: The phase-based feature pattern#

Heavy-path only. Large features, a new block family, a new Inspector panel, a new abilities surface, are run as numbered phases. Cairnstone is the most-exercised example: Phase 9 (Block Bindings + library manifests), Phase 10 (Schema panel), Phase 11 (binding shape stabilisation), Phase 13 (MCP cairnstone/* abilities), and so on, each with its own shape brief, its own craft passes, its own audit, and a clear "shipped at N/N" closure.

A phase has three artefacts:

1. A shape brief, written first via impeccable shape and saved to Z:\Dev\Obsidian\<Plugin>\Plans\ (Drive-backed, in the reasoning vault, outside the repo). The brief locks the scope; expanding it mid-phase requires a new shape pass.
2. A craft sequence, run via impeccable craft, committed in small units with versioned messages (v2.2.135, v2.2.136, …). Each craft commit records its verification result.
3. A closure entry in the per-plugin Z:\Dev\Obsidian\<Plugin>\Plans\DONE-WORK.md when the phase ships at N/N. The shape brief is then deleted; the closure entry is the durable record. The decision vault keeps the strategic record separately (see section 8).

The phase number is part of the commit messages and the changelog entries. A reviewer can ask "what shipped in Phase 9?" and find the answer in Z:\Dev\Obsidian\<Plugin>\Plans\DONE-WORK.md, the corresponding git history, and the per-plugin foundation roadmap published on this docs site.

6: The verification gate#

Nothing is called done on assertion. Done is a check that can be run. For a plugin change the checks are concrete:

Plugins are exercised across a small matrix of three local Studio installations on the operator's workstation (see the ecosystem brief): floor (WordPress 6.9.4 / PHP 8.3), stable (WordPress latest stable / PHP 8.4), and bleeding (WordPress 7.1 / PHP 8.5). The plugin source on the workstation is junction-mounted into all three sites' wp-content/plugins/, so a single edit exercises every slot. Production is different: it is never in any automated path. Production sites are updated only by a person uploading a build by hand. The deliberate gap between local matrix and manual production is the single hard rule that protects the live site.

A second matrix, the theme-context matrix, sits alongside the version matrix above, aimed at rendering-across-themes rather than WordPress-version compatibility, and tested in ISOLATION. Where the three sites above run every plugin active together, each of these four activates only the ONE plugin under test, so a cross-plugin interaction can never corrupt a rendering result. The four differ by active theme: a default theme (csdev), a dark theme (csdevdark), a classic no-block theme (devclassic, Twenty Sixteen), and a full-site-editing block theme (devfse, Ollie); today only Cairnstone is set up on them. Any change that produces a visible result is confirmed on the dark site at minimum, because dark is where a block's own CSS most often loses silently to the theme; the classic and FSE sites catch the two other rendering extremes. This is the human complement to the automated hostile-theme run in the shared viewport-check harness (an aggressive unlayered theme reset injected at boot): the harness proves the geometry survives a hostile theme, the dark site is where a person confirms it actually reads right.

Infrastructure-level safety hooks sit one layer below the per-task gates above. The agent's user-global Claude Code harness carries four hooks: three PreToolUse hooks block specific dangerous operations before they execute (raw rm -rf, edits to wp-config.php, creation of any .env file), and one PostToolUse hook auto-runs php -l on every edited PHP file. These fire on the tool call itself, regardless of agent intent, the soft rules in the harness describe the boundary; the hooks enforce it. Workarounds exist for legitimate cases (rm -r without -f for clean temp dirs; git rm -rf for recoverable git operations; manual edits to wp-config.php in the operating system).

A complementary headless smoke-test path ships with Cairnstone / Core / Node via @wp-playground/cli: a Vitest harness that spins up a disposable WordPress 6.9 / PHP 8.3 instance in WebAssembly, mounts the plugin tree, and asserts activation succeeds without fatal. Faster than driving a full Studio site for cheap activation checks; complements the local matrix rather than replacing it.

A live wp.org-compliance check sits on every local Studio site in the form of Plugin Check (PCP), the official Automattic-maintained review-tool plugin. It is reachable at /wp-admin/admin.php?page=plugin-check on each Studio site (8571.wp.local / 8369.wp.local / 84latest.wp.local). The agent invokes it directly, either by driving the admin URL via Chrome MCP (pick plugin, click Run, scrape findings), or by running the equivalent WP-CLI command (wp plugin check <slug>) via the wp-wpcli-and-ops skill. Because Studio's junctions point at the wp.org-clean mirror (not the dev source), the PCP scan sees only production-relevant files, dev-only artefacts (CLAUDE.md, composer.json, phpstan.*, etc.) are filtered out by the mirror before PCP ever sees them, so findings are real findings. PCP runs the same ruleset as the wp.org submission queue (deprecated functions, sanitisation / escaping, file-system writes, enqueue patterns, i18n compliance, late-escaping, header validation), so a clean PCP pass on the floor site is the closest cheap proxy for "would survive submission review". Reach for it pre-submission and after any change that touches a wp.org-relevant surface (a new escape boundary, a new admin enqueue, an i18n string load).

7: The agent's auto-memory layer#

The agent keeps a persistent file-based memory under its own project directory, separate from both the code repository and the Obsidian decision vault. The memory is built up over many sessions so a fresh conversation arrives with a complete picture of the user, the codebase, and the way the work should be approached.

There are four types of memory, each in its own file in the memory directory and indexed from a top-level MEMORY.md:

What the memory does not hold: anything derivable from current repo state (file paths, conventions, architecture), git history facts, debugging fix recipes, or anything documented in CLAUDE.md. Those are read from source on demand. The memory is reserved for what is genuinely cross-session and non-obvious.

The memory is read when the user references prior work, when a request matches a known feedback rule, or when the session is about to take an action that historic feedback addressed. Stale memories are updated or removed rather than acted on, "the memory says X exists" is not the same as "X exists now". The anthropic-skills:consolidate-memory skill runs a reflective pass periodically to merge duplicates, fix drift, and prune the index.

8: The decision log: the Obsidian vault#

Decisions that matter across sessions, an architectural choice, a technical trade-off, a visual direction, a process change, a floor-lift, a distribution call, are written up as dated notes in an Obsidian vault: a linked-markdown knowledge base that lives outside the code repository. The split is deliberate and has a name.

The two are kept distinct on purpose so the repository stays focused on what users run and the vault stays free for the why.

There is one vault per tool, Node, Cairnstone, Feed, Mesh, and a Core vault that owns the cross-tool reasoning the per-tool vaults cannot: how the tools compose, this shared docs network, the better-together principle, ecosystem-wide conventions, and the global memory that outlives any single plugin.

Vault shape

Each vault opens with a frontal-cortex index: a 00 <Tool> Index note whose top section is a kept-fresh current-state dashboard, the last shipped commit, the working-tree state, the active threads, the parked items, the next obvious step, and the most recent decisions. It is updated in the same change that triggers it; a stale dashboard is treated as worse than none.

Decision notes follow a fixed shape:

• Frontmatter classifying the area (architecture, technical, visual, process, distribution) and a status that flips to superseded with a pointer to the note that replaced it.
• Context: what triggered the decision.
• Decision: what was decided, in one paragraph.
• Rationale: the load-bearing reasons.
• Trade-offs: what was given up.
• Implementation: the concrete commits / files / hooks that landed it.
• Implications: what now changes in the working assumption.
• Sources: the cited commits, files, environments, or external links.

Notes link to each other and to the instruction files with explicit-path wikilinks, so Obsidian builds the backlink graph automatically and a reviewer can walk the reasoning, not just read it.

Vault rules

Two rules keep the vault honest:

1. Cite the source. Every load-bearing claim in a note traces to a verified commit, file, or live environment before the prose is written, no invented commit hashes, no assumed file paths, no untested "it works".
2. The agent does not overwrite the human's thinking. The agent edits its own output freely (the decision notes it wrote, the index it maintains), but user-authored notes and a human's edits to the agent's notes are read first, the diff surfaced, and the change confirmed before anything is overwritten. The vault is the one place the human's reasoning is authoritative over the agent's.

A dated note at Z:\Dev\Obsidian\<Tool>\Decisions\ is required when, and only when, a change crosses one of these four explicit thresholds:

1. The architectural approach locks the project into a specific database/schema footprint that is hard to reverse.
2. A net-new pluggable engine or extension system is introduced.
3. The change directly alters cross-plugin ecosystem behaviours (a structural integration between separate Gillish modules).
4. The system platform floor is officially lifted (WP or PHP minimum moves forward).

For routine helpers, standard settings fields, normal controller implementations, and fast-path or feature-path work that does not match the four triggers above, do NOT suggest or write a decision log entry. The vault is the human's strategic record; protect it from clutter.

The summary read: would a future session need to know why this exists and what was rejected? If yes (and a threshold above applies), a note lands. Every new pluggable surface, a new detector, a shared service, a toggleable module, a new library block, earns a note when it lands; a net-new visual surface additionally cites its Mobbin research; a private one-line helper does not. The payoff is that a reviewer can reconstruct not just what was built but why, and can disagree with the why, which is the entire reason it is written down.

9: Version regulation & the floor-lift discipline#

The studio runs continuous local verification: edits in the canonical plugin tree are reflected in all three local Studio sites at once via NTFS junctions. There is no release ceremony to hang a version bump on, so the rule is structural.

Version regulation

• Bump on every meaningful change in the same commit as the change. Feature, behavioural fix, security fix, schema change, floor lift, all bump. Pure docs / comment / test-only edits do not.
• One bump = three places. The plugin header's Version: line, the constants prefix's version (e.g. GCO_VERSION), readme.txt's Stable tag, and a fresh == Changelog == entry, all in the same commit.
• Major version bumps are reserved. The agent never rolls the major version (the leading number) by itself. Cairnstone's v3.0.0 is held for the wp.org launch; Core's 0.x → 1.0 is the operator's call alone. An agent that proposes a major bump without explicit instruction has failed the doctrine.
• Patch numbers move with floor-lift decisions. When the ecosystem WP or PHP floor lifts, every plugin gets a patch bump even if its own code did not change, the floor is part of the plugin's declared interface.

Floor-lift discipline

The platform floors (WordPress and PHP minimums) only move forward. Each floor lift carries:

1. A technical trigger. Either a specific WP or PHP feature unlocks meaningful product work (Cairnstone's binding work needed block_bindings_supported_attributes from WP 6.9), or the current floor blocks a clean implementation (holding PHP 8.2 means hand-rolling json_validate()), or posture consistency demands it (lifting WP aggressively while holding PHP at an older version is discipline drift).
2. A dated decision note in the Core vault.
3. An ecosystem-wide sweep: every plugin's Requires at least: / Requires PHP: headers and readme.txt values move together, with a patch bump apiece.
4. A floor smoke environment at the new minimum, so the declared floor is exercised on every push, not just declared.
5. An entry on the public version-support page so site owners can read the policy directly.

10: Distribution mechanics#

The studio retired its remote auto-deploy matrix on 2026-05-23 in favour of a local-first arrangement. The mechanics now live on the operator's workstation; the shape:

• Three local Studio installations cover the floor / stable / bleeding matrix at https://8571.wp.local (WordPress 7.1 / PHP 8.5; Studio profile 8571; bleeding), https://8369.wp.local (WordPress 6.9.4 / PHP 8.3; Studio profile 6983; floor), and https://84latest.wp.local (WordPress latest stable / PHP 8.4; Studio profile 84latest; stable). Studio is Automattic's local-WordPress app; each site runs WordPress in WebAssembly.
• Four theme-isolation installs sit alongside those three (csdev, csdevdark, devclassic, devfse), on the same junction chain but differing by active theme (default / dark / classic / FSE) and run with only the single plugin under test active, for uncontaminated per-theme rendering checks (see §6).
• Single canonical plugin tree at Z:\Dev\Code\<plugin>. Every Studio site's wp-content/plugins/<plugin> entry is an NTFS junction pointing into the production-clean mirror at Z:\Dev\Code backups\<plugin> (not the dev tree directly, see the mirror script below). Editing the source is reflected in all three sites simultaneously after a mirror refresh.
• Production-clean view via a mirror script. Z:\Dev\Code\.tools\mirror.ps1 -Live runs a robocopy from Code\<plugin> into Code backups\<plugin>, stripping two categories: regenerable cache (node_modules, vendor, vendor-runtime, .git, build, dist, logs, .tmp.driveupload) and PCP false-positives (.claude, CLAUDE.md, DESIGN.md, PRODUCT.md, README.md, CHANGELOG.md, phpcs.*, phpstan*, phpunit.xml.dist, .phpunit.result.cache, composer.*, package.*, .gitignore, .gitmodules). The Studio junctions point at this stripped mirror, so PCP and the running WP instance see only production-relevant files. Runs after every substantive code change so Studio's junction sees the new state; also runs as the Google Drive backup refresh.
• Production-ship-worthy snapshots. Z:\Dev\Code\.tools\make-zip.ps1 <plugin> writes Z:\Dev\Code backups\<plugin>.zip with a 10-file rotation of timestamped historicals. Trigger is ship-worthy changes only, version bumps, behaviour-changing fixes, schema migrations, anything that would be uploaded to a production site. Routine refactors, doc-only edits, and intermediate WIP commits do not trigger a zip; the mirror catches them. Z:\Dev\Code\.tools\audit-gate.ps1 runs the combined composer audit + npm run test:a11y gate per plugin (see §6).
• Pre-push gates run in-session. Before every git push origin main on Core / Cairnstone / Node, the agent runs composer audit + the wp-playground accessibility scan. Failures hold the push. Replaces the retired GitHub-Actions audit + a11y workflow.
• GitHub repos are backup-only. Pushing to main serves only as off-machine code backup; no workflow deploys anywhere from there.
• Production is manual zip upload, always. Production sites are never in any automated path. wp.org submission is the same shape: a manual zip uploaded to the Plugin Directory.

The full description and the rationale for each piece live in the ecosystem product brief.

11: How this site is produced#

This documentation network, html.gillish.com, is its own repository, separate from any plugin. Updates are pushed to the live server via a local rsync over SSH, additive-only, invoked by the operator (the previous GitHub-Actions auto-deploy was retired 2026-05-24 alongside the plugin auto-deploy matrix). The plugins do not bundle, deploy, or own the docs site; the docs site does not depend on any plugin.

Per-tool pages are partly hand-authored and partly generated from the plugins' own machine-readable manifests, so a block's description on the site and its behaviour in the code cannot drift apart: change the manifest, regenerate, and both move together. Where pages are hand-authored, the docs-site SEO skill family (searchfit-seo:*, marketing:brand-review) runs as the final pass.

Two rules keep the public docs honest:

• Cite the source. Every load-bearing claim on a public page traces to a verified commit, file, or live environment. Memory-written docs once landed several confident, wrong claims; the rule is now structural.
• Current truth only. Public docs pages carry the current state, never the resolved-internal-history narrative. "Previously had X, now Y, see <internal note>" stays in the Obsidian vault (decision notes and the per-tool Plans\ subfolders), it never appears on a published page. Internal Obsidian filenames are not referenced on public pages.

12: Standing conventions#

A few rules apply to every session regardless of the task.

• One language in the product. Everything shipped, every visible string, label, comment, commit message, is in English. The studio's working conversation can be in Norwegian; the artefact never is. Mixed-language UI signals amateur.
• Build for humans, not developers. Every shipped surface is for site owners and editors, not the developer who built it. Pick a value from a list, do not type a code. Show the human label, store the technical id. Help text answers "what do I type here", with examples.
• Light + dark mode together. Write the light rule first, then the body.<prefix>-dark-mode override immediately below. No one-off shades; reuse the project's palette. html.gillish.com is the named exception, this docs site is light-only by design; Gillish plugins still ship both themes.
• Single hook registry per plugin. Every add_action / add_filter lives in the plugin's register_hooks() method, nowhere else.
• Sibling detection is one-line. Cross-tool integration uses class_exists( '\Gillish\<Tool>\Plugin', false ); never a hard use Gillish\… import.
• Always offer the next three steps. When a unit of work completes, the session ends with exactly three concrete next options, each with a one-line reason anchored to the state just reached, so the maintainer always has a clean way to redirect.
• Auto-commit, auto-push after meaningful changes. The harness is configured to commit and push without asking; GitHub's revert mechanics make this low-risk and the workflow stays fast. The agent never asks "should I commit?" after a code change, it just commits.

13: Compliance guardrails & the CRA program#

GDPR, CCPA, the EU Cyber Resilience Act, OWASP, and WCAG 2.2 AA are not handled per task; they are permanent guardrails in the doctrine, so the posture cannot drift session to session. The guardrails are deliberately written as what not to do, because in a WordPress plugin the common compliance reflexes are the dangerous ones.

The EU Cyber Resilience Act program

Core owns the ecosystem-wide CRA program for the whole studio. It runs in two operational phases:

1. Phase 1, operational baseline. A public coordinated-vulnerability-disclosure (CVD) policy, security.txt at the well-known location, the public posture pages on this site, the SBOM publication routine, and the internal incident-response runbook. Live across the ecosystem since 2026-05-19.
2. Phase 2, Annex I gap audit. Fourteen Part-I cited rows + eight Part-II cited rows, mirrored across Core, Cairnstone, and Node security pages. The first CycloneDX 1.5 SBOM ships in parallel; the public mirror at core/security/#annex-i is the canonical visible surface. Landed 2026-05-20.

Operational continuation: the static Phase 2 SBOM baseline is complemented by composer audit as an in-session pre-push gate on every push to main across Core / Cairnstone / Node. Each push runs composer audit --format=plain against the resolved lockfile; an open Packagist advisory holds the push until resolved or explicitly waived. Closes the per-release gap between the static SBOM baseline and the live dependency state. Free, no external SaaS, no new repo secrets. Feed and Mesh are skeleton-state and join when their toolchains stand up.

14: How to give input#

This page exists so the process can be argued with. If a step looks wrong, missing, or over-engineered, that is the useful signal. Concrete places it is worth pushing back:

• The gates. Are the right things gated behind a human, and is anything gated that should not be, or automated that should not be?
• The doctrine. Do the four principles still describe how the work should go, or has a fifth failure mode shown up often enough to earn its own rule?
• The skills layer. Is a skill missing from this manual that the studio actually uses? Is a listed skill no longer load-bearing and should be retired from the description?
• The MCP inventory. Is the right server picked at the right tier, or is the agent reaching for Computer-use MCP when Chrome MCP would do?
• The pipeline order. Is research-then-shape-then-craft the right sequence for the kind of work being done now, or does some class of change deserve a shorter path?
• What is missing. The honest gap in this document is the most valuable thing a reviewer can name.

Input goes back to the maintainer directly. This is a working document; it is expected to change, and the change history is part of the record. The Last revised date in the page header is when it was last touched in a non-trivial way.