akili-specs 2.1.0

package/.claude/commands/akili-execute.md

@@ -0,0 +1,240 @@
+---
+description: Execute approved specs systematically following the AKILI-SPECS methodology with spec-to-code traceability.
+---
+
+# Execute AKILI-SPECS Tasks
+
+Execute implementation tasks from an approved AKILI-SPECS spec path using the AKILI **Leader → Implementer → Reviewer** multi-agent triad. Read `tasks.md`, choose the next eligible task, delegate implementation, audit the diff, retry on failure (max 3 attempts), update task status, and record the full audit trail in `execution.md`.
+
+Execution should be incremental. Do not turn one approved task into a broader refactor unless the spec explicitly requires it or the user approves the scope change.
+
+## Usage
+
+```
+/akili-execute <spec-path>
+```
+
+**Examples:**
+
+- `/akili-execute loan`
+- `/akili-execute enhancements/renewals`
+
+## Arguments
+
+- `$ARGUMENTS` — Relative path under `docs/specs/` that already contains `requirements.md`, `design.md`, and `tasks.md`.
+
+## Output
+
+Each successful task execution should produce:
+
+- focused code or documentation changes within task scope
+- updated task status in `tasks.md`
+- an appended audit entry in `execution.md` covering every Implementer attempt and every Reviewer verdict
+- verification evidence from the command or check listed in the task
+- a Reviewer PASS verdict before the task is marked complete
+
+Use `[~]` for a started but incomplete or blocked task, `[x]` for a completed task, and `[ ]` for pending work.
+
+---
+
+## Multi-Agent Triad
+
+In this command you act as the **Leader** (Orchestrator). You delegate concrete work to two subordinate agent roles defined in the project's `.agents/` directory:
+
+- `.agents/leader.md` — orchestration rules and audit conventions (your own playbook).
+- `.agents/implementer.md` — the persona used when delegating implementation.
+- `.agents/reviewer.md` — the persona used when delegating spec-conformance audit.
+
+If `.agents/` is missing, run `/akili-constitution` first to scaffold it. Do not invent personas inline — the constitution is the source of truth.
+
+**Delegation mechanism by tool:**
+
+- **Claude Code / OpenCode:** spawn a focused subagent (or sub-prompt context) seeded with the persona file plus the task/diff context.
+- **Google Antigravity:** invoke `invoke_subagent` (or the equivalent workflow primitive) using prompts read from `.agents/`.
+
+The Leader does not write production code itself unless the rework loop is exhausted and the user has explicitly approved a fallback.
+
+---
+
+## Behavior
+
+### Step 0: Load Context
+
+**Token Optimization (Prompt Caching):** To maximize prompt caching, always read the constitutional baseline documents FIRST and in the exact same order across all sessions before reading task-specific files.
+
+1. Read the project constitutional docs (IN THIS ORDER):
+   - root `CLAUDE.md`
+   - `AGENTS.md`
+   - `docs/prd.md`
+   - `docs/ux-ui/design.md` (legacy fallback: `docs/system-design/design.md`)
+   - `docs/trd/trd.md` (legacy fallback: `docs/detailed-design/detailed-design.md`)
+   - `docs/specs/general-setup/`
+   - Package-level `CLAUDE.md` and `AGENTS.md` files if they exist
+2. Read the AKILI-SPECS documents for the spec path:
+   - `docs/specs/$ARGUMENTS/requirements.md`
+   - `docs/specs/$ARGUMENTS/design.md`
+   - `docs/specs/$ARGUMENTS/tasks.md`
+3. Read `docs/specs/$ARGUMENTS/execution.md` if it exists.
+4. Read the agent personas:
+   - `.agents/leader.md`
+   - `.agents/implementer.md`
+   - `.agents/reviewer.md`
+5. Identify current task state: `[x]`, `[~]`, `[ ]`.
+
+### Step 1: Select Next Task(s)
+
+1. Find the next executable task by document order where:
+   - status is `[ ]` or `[~]`
+   - all dependencies are `[x]`
+2. If a task is `[~]`, resume it using `execution.md` context.
+3. If no tasks are eligible, report completion or blocking state and stop.
+4. **Parallel Execution:** If multiple tasks are eligible AND they are completely independent (e.g., they touch completely different domains or files), you MAY spawn multiple Implementers in parallel to execute them concurrently. Otherwise, prefer executing the first task by document order to avoid merge conflicts.
+
+### Step 2: Execute Task via Rework Loop
+
+The Leader executes each task through a bounded loop. The loop terminates on Reviewer `PASS`, on HALT after 3 failed attempts, or on a Pivot.
+
+```text
+attempt = 1
+feedback = none
+loop:
+  spawn Implementer with task scope + design context + feedback (if any)
+  receive Implementer report (changes + verification evidence)
+  extract git diff
+  spawn Reviewer with diff + spec context
+  receive Reviewer verdict (PASS | FAIL)
+  if PASS:
+    finalize task (Step 3)
+    exit loop
+  else (FAIL):
+    append FAIL findings to execution.md
+    if attempt >= 3:
+      HALT, mark task [~], present audit trail (Step 4)
+      exit loop
+    feedback = Reviewer issues
+    attempt += 1
+    continue loop
+```
+
+#### 2.1 — Read Scope & Design (Leader)
+
+- Re-read the specific design sections referenced by the task.
+- Re-read the requirements and scenarios covered by the task.
+- Identify the smallest safe change that satisfies the task.
+- Identify the verification command listed in the task.
+
+#### 2.2 — Spawn Implementer
+
+Delegate to the Implementer with:
+
+- the persona content from `.agents/implementer.md`
+- the active task ID, title, and scope from `tasks.md`
+- the relevant slices of `requirements.md`, `design.md`, and `trd.md`
+- the project constitution references (`CLAUDE.md`, `AGENTS.md`, `docs/ux-ui/design.md`)
+- the recommended skill list from the task (e.g. `ui-ux-pro-max`, `react-doctor`, `nestjs-expert`)
+- any prior Reviewer feedback when this is a rework attempt
+- the verification command to run before reporting completion
+
+The Implementer must keep changes minimal and within task scope, follow the design spec exactly unless the spec is clearly incomplete or contradictory, and run the verification before reporting completion.
+
+#### 2.3 — Spawn Reviewer
+
+When the Implementer reports completion, the Leader:
+
+1. Extracts the **git diff** of changes since the start of the attempt. To save tokens, the Reviewer MUST ONLY be given the diff, not the entire source files, unless absolutely necessary for context.
+2. Spawns the Reviewer with:
+   - the persona content from `.agents/reviewer.md`
+   - the **git diff**
+   - the relevant slices of `requirements.md`, `design.md`, `trd.md`, and `docs/ux-ui/design.md`
+   - the Implementer's verification evidence
+
+The Reviewer is read-only. It must conclude with either:
+
+- **`STATUS: PASS`** + a 1–2 sentence summary
+- **`STATUS: FAIL`** + a structured list of issues, each containing:
+  1. **Discovered Issue** — what is incorrect or missing
+  2. **Violated Rule** — the specific spec document and section violated
+  3. **Remediation Suggestion** — what the Implementer must change
+- **`STATUS: FATAL_FAIL`** — Used ONLY if the Reviewer detects a critical architectural violation, a broken fundamental design token, or a completely unviable approach that cannot be fixed by simple iteration. This triggers an immediate abort of the rework loop (Fail-Fast) to save tokens.
+
+#### 2.4 — Loop Guardrails
+
+- **Maximum Retries:** A hard ceiling of **3 rework attempts** per task. This prevents infinite loops and token waste.
+- **Fail-Fast (FATAL_FAIL):** If the Reviewer issues a `STATUS: FATAL_FAIL`, immediately HALT the loop, mark the task `[~]`, and trigger the Pivot Protocol. Do not consume remaining rework attempts.
+- **Structured Feedback:** On `FAIL`, pass the full Reviewer report unchanged to the next Implementer spawn. Do not paraphrase.
+- **Escalation on HALT:** After 3 failed attempts (or a FATAL_FAIL), mark the task `[~]`, log the full loop history in `execution.md`, and present the audit trail to the user for guidance.
+- **Pivot Detection:** If either the Implementer or the Reviewer surfaces evidence that the spec itself is wrong or unviable (not merely the implementation), stop looping immediately and trigger the Pivot Protocol below — do not consume rework attempts on a broken spec.
+
+### Step 3: Finalize on PASS
+
+Only after a Reviewer `PASS`:
+
+1. Update `tasks.md` from `[ ]` (or `[~]`) to `[x]`.
+2. Append a structured entry to `execution.md` (see log format below) covering every attempt in this task's loop.
+3. **Git Commit Staging:** Always follow the **AKILI Spec Reference** commit standard. Prefix the commit message with `[SPEC:<spec-path>]` (e.g. `git commit -m "[SPEC:changes/add-remember-me] implement secure cookie storage"`).
+4. **Code Traceability:** Add file-level or block-level comment spec references (`// @akili-spec <spec-path>`) in critical or complex codebase additions to assist future audits.
+5. **Constitution Impact Check:** If the task created a new module/package, moved a module boundary, or changed a module's public surface, append a `## Constitution Impact: <Task ID>` block to `execution.md` recording:
+   - which module was created or reshaped
+   - whether a child `CLAUDE.md`/`AGENTS.md` is needed for it (or an existing child guide became stale)
+   - which parent guide's `## Module Guides` index needs a new or updated reference
+   - that a CodeGraph re-index is pending
+   These notes are consumed by `/akili-archive` (Constitution & Graph Sync). If skipping the sync until archive would leave the root guides actively misleading (e.g. a new top-level package agents keep guessing about), update the affected guides immediately in the same task commit instead of deferring.
+
+### Step 4: HALT on Rework Limit
+
+If 3 attempts fail in a row (or a FATAL_FAIL occurs):
+
+1. **Automatic Rollback:** Run `git restore .` and `git clean -fd` to revert the working tree to a clean state. Do not leave broken code for the user to clean up.
+2. Mark the task `[~]` in `tasks.md`.
+3. Append a final `## HALT: <Task ID>` block to `execution.md` containing:
+   - all three Reviewer `FAIL` reports
+   - all three Implementer summaries
+   - the verification output of the final attempt
+   - the Leader's hypothesis on the root cause (spec ambiguity, missing context, environmental issue, etc.)
+3. Present the blocker to the user with a clear question — for example: *"The Reviewer rejected three attempts on the same `design token compliance` finding. The spec at `design.md#tokens` does not list a token for this surface. How would you like to proceed?"*
+4. Do **not** advance to the next task automatically after a HALT.
+
+### Step 5: Continue or Pause
+
+After a task PASSes or HALTs, generate a short, easy-to-understand summary (summary facil de entender de lo que se hizo) of the task result, verification outcome, the Reviewer summary, and the next eligible task. Ask whether to continue, pause, or skip the next task.
+
+---
+
+## Execution Log Format (`execution.md`)
+
+The execution log is created on first run and appended to on subsequent runs. It is the canonical audit trail of the multi-agent loop.
+
+Minimum sections:
+
+1. Document Control
+2. Task Execution History
+3. Summary when all tasks are complete
+
+Each task entry must record:
+
+- final status (PASS / HALT / pivot)
+- date
+- task ID and title
+- number of Implementer attempts run
+- for each attempt: files changed, Implementer verification command + result, Reviewer verdict + summary or full FAIL findings
+- requirements covered
+- decisions made
+- issues encountered
+- final verification result
+
+A minimal PASS-on-first-attempt entry can be compact; a HALT or rework entry must include the full attempt-by-attempt history.
+
+---
+
+## Error Handling & Pivot Protocol
+
+- If required AKILI-SPECS files are missing, stop and report what is missing.
+- If `.agents/` is missing, stop and direct the user to run `/akili-constitution`.
+- If the design is ambiguous, the Leader asks the user before spawning the Implementer — do not pass an ambiguous task into the loop.
+- If verification fails inside the Implementer, the Implementer must fix it before reporting completion; if it cannot, it reports back the failure and the Leader treats that as an implicit FAIL.
+- If a task is blocked, report the blocker and move to the next eligible task only if appropriate.
+- **Pivot Protocol:** If Implementer or Reviewer discoveries reveal that the approved requirements or design are wrong or technically unviable:
+  1. Stop the rework loop. Mark the current task as `[~]` (blocked) — even if rework attempts remain.
+  2. Document the blocker, alternatives, and revised technical direction in `execution.md` inside a new `## Pivot Record: <Task ID>` section.
+  3. Modify the spec's `requirements.md`, `design.md`, and/or `tasks.md` to map out the updated plan.
+  4. Stop, explain the situation to the user, and obtain explicit review/approval on the pivot before resuming execution.

package/.claude/commands/akili-propose.md

@@ -0,0 +1,167 @@
+---
+description: Propose new features or changes by initiating a new detailed technical spec process.
+---
+
+# Propose AKILI-SPECS Change
+
+Create a lightweight proposal for one bounded change before generating full AKILI-SPECS documents.
+
+The proposal is the reviewable intent layer. It should help the user decide whether the change is worth specifying before time is spent on requirements, design, tasks, or implementation.
+
+> **Recommended model tier:** T1 Architect (deep reasoning, architecture, trade-offs). Ensure you are using the strongest reasoning model available for this phase.
+
+## Usage
+
+```
+/akili-propose <change-name-or-spec-path>
+```
+
+**Examples:**
+
+- `/akili-propose add-remember-me`
+- `/akili-propose bugfix/login-redirect`
+- `/akili-propose enhancements/renewals`
+
+## Arguments
+
+- `$ARGUMENTS` - A change name or a relative path under `docs/specs/`.
+
+Path resolution:
+
+- If `$ARGUMENTS` contains `/`, treat it as the literal spec path.
+- If `$ARGUMENTS` is a bare name, use `changes/$ARGUMENTS` as the spec path.
+
+Examples:
+
+| Input | Spec Path | Proposal Path |
+|---|---|---|
+| `add-remember-me` | `changes/add-remember-me` | `docs/specs/changes/add-remember-me/proposal.md` |
+| `bugfix/login-redirect` | `bugfix/login-redirect` | `docs/specs/bugfix/login-redirect/proposal.md` |
+
+## Output
+
+Create or update:
+
+```text
+docs/specs/$SPEC_PATH/proposal.md
+```
+
+Do not create `requirements.md`, `design.md`, or `tasks.md` in this command unless the user explicitly asks. Those belong to `/akili-specify`.
+
+## Behavior
+
+### Step 0: Resolve Path And Load Context
+
+**Token Optimization (Prompt Caching):** To maximize prompt caching, always read the constitutional baseline documents FIRST and in the exact same order across all sessions before reading task-specific files.
+
+1. Resolve `$SPEC_PATH` using the path rules above.
+2. Create `docs/specs/$SPEC_PATH/` if it does not exist.
+3. Read project-level context when available (IN THIS ORDER):
+   - root `CLAUDE.md`
+   - `AGENTS.md`
+   - `docs/prd.md`
+   - `docs/ux-ui/design.md` (legacy fallback: `docs/system-design/design.md`)
+   - `docs/trd/trd.md` (legacy fallback: `docs/detailed-design/detailed-design.md`)
+   - `docs/specs/general-setup/`
+   - package-level `CLAUDE.md` files
+4. Read nearby or related specs under `docs/specs/`.
+5. **CodeGraph over full reads:** If `.codegraph/` exists, use `codegraph_search` and `codegraph_context` to inspect relevant code paths instead of reading full source files or using generic `grep`/`glob`. This drastically reduces input tokens.
+
+### Step 1: Clarify Intent, Sources & Scope Chunking
+
+Before diving into the problem, ask the user about the source of the requirements and any visual designs:
+
+1. **Requirement Source:** Ask if they have a **Jira ticket** (if they do, suggest using the **Jira MCP** to automatically extract the description, acceptance criteria, and comments created by the BA) or if they prefer to paste/write the context directly.
+2. **Visual Designs / Mockups:** Ask if there is a **Figma link** or any visual mockup available. If they provide a Figma URL, suggest using the **Figma MCP** to extract the design details, components, and layout information.
+
+Use `brainstorming` and, when helpful, `product-manager-toolkit` to clarify:
+
+- problem being solved
+- target users, actors, or systems
+- current behavior
+- desired behavior
+- scope boundaries
+- non-goals
+- dependencies and constraints
+- success criteria
+
+**Scope Chunking:** If the user provides a very large or multi-faceted instruction (e.g., an entire epic or multiple distinct features), analyze whether the request should be split into multiple bounded proposals.
+- If it should be split, propose breaking it down to the user.
+- Upon agreement, create the respective folders for each bounded change under `docs/specs/` and generate a `proposal.md` for each.
+
+Ask focused questions only when the proposal would otherwise depend on unstable assumptions.
+
+### Step 2: Write `proposal.md`
+
+Create a concise proposal with this structure:
+
+1. Document Control
+2. Intent
+3. Problem / Current Behavior
+4. Proposed Outcome
+5. Scope
+6. Non-Goals
+7. Affected Users, Systems, And Specs
+8. Requirement Delta Preview
+9. Approach Options
+10. Recommended Approach
+11. Risks, Dependencies, And Open Questions
+12. Success Criteria
+13. Next Step
+
+### Requirement Delta Preview
+
+When the change affects existing behavior, include a lightweight preview using these sections where relevant:
+
+```markdown
+## Requirement Delta Preview
+
+### ADDED Requirements
+
+- New behavior that does not exist today.
+
+### MODIFIED Requirements
+
+- Existing behavior that will change.
+
+### REMOVED Requirements
+
+- Existing behavior that will be deprecated or deleted.
+```
+
+This preview is not the final spec. `/akili-specify` converts approved intent into full requirements, scenarios, design, and tasks.
+
+### Approach Options
+
+For non-trivial work, include 2 or 3 options with trade-offs. Recommend one option and explain why it is the smallest safe path.
+
+### Next Step
+
+End the proposal with the exact next command:
+
+```text
+/akili-specify $SPEC_PATH
+```
+
+## Review Checklist
+
+Before presenting the proposal, verify:
+
+- [ ] The problem is clear.
+- [ ] Scope and non-goals are explicit.
+- [ ] The proposed outcome is behavior-focused.
+- [ ] Affected specs or code areas are listed.
+- [ ] Risks and open questions are visible.
+- [ ] The next command uses the resolved spec path.
+
+## Report To User
+
+Generate a short, easy-to-understand summary (summary facil de entender de lo que se hizo) that reflects what was done. It must include:
+
+1. proposal path
+2. resolved spec path
+3. recommended approach
+4. main risks or open questions
+5. next command to run after approval
+
+Ask whether to approve the proposal, revise it, or stop.

package/.claude/commands/akili-seo.md

@@ -0,0 +1,277 @@
+---
+description: Enhance pages and search engine optimization following SEO best practices.
+---
+
+# SEO Setup & Audit via Google Search Console
+
+Provision Google Search Console access for a domain via a Google Cloud service account, then run a full SEO audit (index coverage, sitemaps, structured data, search analytics) and generate an audit report under the spec path. Produces `seo-setup-report.md` and `seo-audit-report.md`.
+
+## Usage
+
+```
+/akili-seo <site-domain>
+```
+
+**Examples:**
+
+- `/akili-seo calismiledesign.com`
+- `/akili-seo seo/calismiledesign.com`
+- `/akili-seo agrosmartco.com`
+
+## Arguments
+
+- `$ARGUMENTS` — Either a bare apex domain (e.g. `example.com`) or a relative path under `docs/specs/` (e.g. `seo/example.com`). When a bare domain is given, the spec path defaults to `docs/specs/seo/<domain>/`.
+
+## Prerequisites
+
+The user must provide (or confirm) once per Google Cloud project:
+
+1. A Google Cloud service account JSON key file, absolute path.
+2. Three APIs enabled in that GCP project:
+   - **Site Verification API** (`siteverification.googleapis.com`)
+   - **Search Console API** (`searchconsole.googleapis.com`)
+   - **Web Search Indexing API** is **NOT required** — Google only honors it for `JobPosting` and `BroadcastEvent` schemas; do not push users to enable it for generic content sites.
+3. DNS provider access for the target domain (to add a TXT record).
+4. The GSC MCP server configured in `~/.claude.json` or project `.mcp.json` with:
+   ```json
+   "gsc": {
+     "command": "npx",
+     "args": ["-y", "@mikusnuz/gsc-mcp"],
+     "env": {
+       "GSC_SERVICE_ACCOUNT_KEY_PATH": "<absolute path to JSON key>"
+     }
+   }
+   ```
+   If `GSC_SITE_URL` is set, prefer the `sc-domain:` form (e.g. `sc-domain:example.com`) over the URL-prefix form.
+5. A local helper for the Site Verification API. The `gsc` MCP does **not** expose Site Verification endpoints (no `getToken`, no `verify`) — it only wraps the Search Console API. Use the bundled `scripts/gsc_verify.py` from `akili-specs` (depends on `google-auth` and `google-api-python-client`). Invoke it as:
+
+   ```bash
+   GSC_KEY_PATH=/abs/path/to/key.json python3 scripts/gsc_verify.py get <domain>
+   GSC_KEY_PATH=/abs/path/to/key.json python3 scripts/gsc_verify.py verify <domain>
+   ```
+
+If any prerequisite is missing, stop and report exactly what is missing and how to obtain it.
+
+## Tool Inventory
+
+| Phase | Endpoint | Source |
+|---|---|---|
+| 1.1 Get TXT token | `siteVerification.webResource.getToken` | Site Verification API (helper script) |
+| 1.3 Verify ownership | `siteVerification.webResource.insert` | Site Verification API (helper script) |
+| 1.4 Add property | `sites_add` | `gsc` MCP |
+| 1.5 Confirm | `sites_list` | `gsc` MCP |
+| 2.1 Sitemaps | `sitemaps_list`, `sitemaps_submit` | `gsc` MCP |
+| 2.2 Index coverage | `url_inspection_inspect` | `gsc` MCP |
+| 2.4 Analytics | `search_analytics_query` | `gsc` MCP |
+| 2.5 Render | raw `curl -A Googlebot/2.1` | shell |
+
+---
+
+## Behavior
+
+### Phase 0: Setup
+
+1. Resolve the spec path. If `$ARGUMENTS` is a bare domain, set `SPEC_PATH = seo/<domain>`. Otherwise treat `$ARGUMENTS` as the literal spec path.
+2. Create directory `docs/specs/$SPEC_PATH/` if it does not exist.
+3. Read the constitutional templates and project context as defined in `akili-specify`:
+   - `docs/specs/general-setup/`
+   - `docs/prd.md`
+   - `docs/ux-ui/design.md` (legacy: `docs/system-design/design.md` or `docs/system-design.md`)
+   - `docs/trd/trd.md` (legacy: `docs/detailed-design/detailed-design.md` or `docs/detailed-design.md`)
+   - Root `CLAUDE.md`
+4. Confirm the GSC MCP is reachable. If not, stop and report.
+
+---
+
+### Phase 1: Verify & Add Property
+
+**Role:** SEO Engineer — register the service account as a verified owner of the domain in Google Search Console.
+
+#### Step 1.1 — Generate the DNS TXT token
+
+Call the Site Verification API to obtain the verification token for `sc-domain:<domain>`. Present the user with the exact TXT record to add:
+
+```
+Type:  TXT
+Host:  @  (root of <domain>)
+Value: google-site-verification=<token>
+```
+
+#### Step 1.2 — Wait for DNS propagation
+
+Ask the user to confirm the TXT record is live, then verify with a DNS lookup before proceeding. Do not loop silently — fail clearly if propagation has not happened after a reasonable check.
+
+#### Step 1.3 — Verify ownership
+
+Call the Site Verification API `verify` endpoint. On success, the service account becomes an owner of the property.
+
+#### Step 1.4 — Add the property to Search Console
+
+Verification alone does not add the property to Search Console for the service account. Explicitly call `sites_add` with `sc-domain:<domain>` so the property appears in `sites_list` with `permissionLevel: siteOwner`.
+
+#### Step 1.5 — Write `seo-setup-report.md`
+
+Produce `docs/specs/$SPEC_PATH/seo-setup-report.md` documenting:
+
+1. Document Control (date, domain, service account email, GCP project)
+2. Prerequisites checked
+3. DNS TXT record value installed
+4. Verification result
+5. `sites_list` confirmation output
+6. Notes / caveats
+
+---
+
+### Phase 2: Audit
+
+**Role:** Technical SEO Auditor — measure the state of the domain in Google's index.
+
+**Required skill:** load `seo-audit` before starting this phase and apply it throughout:
+
+- Sequence and weight findings by its priority order: crawlability & indexation → technical foundations → on-page → content quality → authority.
+- Record every finding with its structure: **Issue / Impact / Evidence / Fix / Priority**.
+- Respect its schema-detection limitation: static fetches (`curl`, `web_fetch`) cannot see JS-injected JSON-LD. Validate structured data via `url_inspection_inspect.richResultsResult` or a rendering tool, never via static HTML alone.
+- Apply its International SEO checklist (hreflang reciprocity, self-reference, `x-default`, cross-locale canonicals, locale sitemaps) whenever the site serves multiple languages or regions.
+
+Use `systematic-debugging` when results are inconsistent with site reality.
+
+Skill preference for any UX/UI recommendations:
+
+- `ui-ux-pro-max` if available
+- otherwise `frontend-design`
+
+#### Step 2.1 — Sitemap audit
+
+1. List submitted sitemaps via `sitemaps_list`.
+2. If none submitted but `https://<domain>/sitemap.xml` or `/sitemap-index.xml` exists, propose submission with `sitemaps_submit` and ask before submitting.
+3. Fetch each sitemap with `curl -sL` and enumerate URLs.
+
+#### Step 2.2 — Index coverage
+
+For every URL in the sitemap (cap at 25 for cost; sample evenly across locales and sections), call `url_inspection_inspect`. Bucket each URL into:
+
+- `PASS` — Submitted and indexed
+- `NEUTRAL` — Discovered – currently not indexed
+- `NEUTRAL` — URL is unknown to Google
+- `NEUTRAL` — Page with redirect
+- `FAIL` — anything else (e.g. blocked, server error, soft 404)
+
+Record `googleCanonical`, `userCanonical`, `pageFetchState`, `crawledAs`, `lastCrawlTime` for each.
+
+#### Step 2.3 — Structured data audit
+
+From `url_inspection_inspect.richResultsResult`, collect every rich-result item flagged with `WARNING` or `ERROR`. For each, fetch the page with a Googlebot user agent and extract the offending JSON-LD block so the report can show the exact bad value and the exact corrected value.
+
+Common findings to surface:
+
+- `VideoObject.uploadDate` missing time or timezone (use ISO 8601 `YYYY-MM-DDTHH:MM:SS±HH:MM`)
+- `Product`, `Review`, `Organization` missing required fields
+
+#### Step 2.4 — Search analytics
+
+Call `search_analytics_query` for the last 28 days (or last 90 if available), grouped by:
+
+- `query` (top 25)
+- `page` (top 25)
+- `country` (top 10)
+- `device` (all)
+
+If the property is newly verified and returns no rows, record that explicitly and note that data typically appears within 2–7 days.
+
+#### Step 2.5 — Render audit
+
+For 2–3 sampled pages, fetch them with `curl -sL -A "Googlebot/2.1"` and measure:
+
+- HTML size in bytes
+- Visible text length in characters and word count
+- Whether the main content is present in server-rendered HTML (vs JS-only)
+
+This separates "thin content" failures from "JS render" failures.
+
+#### Step 2.6 — Internal linking quick check
+
+Fetch the homepage and count anchor links to each sitemap URL. URLs with zero internal links from the homepage are flagged as orphan-like.
+
+#### Step 2.7 — On-page audit (`seo-audit` framework)
+
+For the pages sampled in Step 2.5, apply the on-page checklist from the `seo-audit` skill:
+
+- Title tags: unique per page, ~50–60 characters, primary keyword near the beginning.
+- Meta descriptions: unique per page, ~150–160 characters, clear value proposition.
+- Heading structure: exactly one H1, no skipped levels, headings describe content.
+- Image alt text present and descriptive; internal anchor text descriptive (no bare "click here").
+- Canonical tags: self-referencing on unique pages, consistent protocol/host/trailing-slash.
+- Multilingual sites: hreflang set includes a self-reference and reciprocal return links, `x-default` declared, each locale self-canonical (never cross-locale).
+
+Record each failure as a finding using the skill's Issue / Impact / Evidence / Fix / Priority structure.
+
+---
+
+### Phase 3: Write `seo-audit-report.md`
+
+Generate `docs/specs/$SPEC_PATH/seo-audit-report.md` using `docs/specs/general-setup/validation-report.md` as the format source where it fits.
+
+Required sections:
+
+1. Document Control
+2. Executive Summary — one-paragraph verdict + 3–5 bullet headline findings.
+3. Index Coverage Table — every audited URL with its bucket and last crawl time.
+4. Sitemap Status
+5. Structured Data Findings — exact broken JSON-LD blocks with corrected versions.
+6. Search Analytics Summary — top queries / pages / devices / countries, or an explicit "no data yet" note.
+7. Render Audit
+8. Internal Linking Findings
+9. On-Page SEO Findings — Step 2.7 results, each in the `seo-audit` Issue / Impact / Evidence / Fix / Priority format.
+10. Remediation Plan — prioritized (High / Medium / Low) actionable items, each scoped enough that an implementer can execute it without further discovery.
+11. Re-audit Schedule — when to run `/akili-seo <domain>` again.
+
+The report title must be `# SEO Audit Report — <domain>`.
+
+---
+
+### Phase 4: Generate a Fix Prompt
+
+Append to the audit report a section titled `## Implementation Prompt` containing a fenced, copy-paste prompt that can be handed to Claude Code (or any engineer) inside the site's codebase to fix every High-severity finding. The prompt must:
+
+- Reference each finding by ID from the remediation plan.
+- Include exact JSON-LD before/after snippets where structured data is broken.
+- Include exact URL pairs for hreflang corrections.
+- End with "Show me a diff of every change before applying. Do not deploy until I approve."
+
+---
+
+### Phase 5: Present & Approve
+
+Present a short summary of:
+
+- Setup status (Phase 1 outcome).
+- Audit headline findings and counts per bucket.
+- The number of High / Medium / Low remediation items.
+- Paths to the two generated reports.
+
+Ask the user whether to also run the same flow against any other properties under the same service account.
+
+---
+
+## Verification Checklist
+
+After the command completes, verify:
+
+- [ ] `docs/specs/$SPEC_PATH/seo-setup-report.md` exists and references the actual TXT token used.
+- [ ] `docs/specs/$SPEC_PATH/seo-audit-report.md` exists with all required sections.
+- [ ] `sites_list` shows the property with `permissionLevel: siteOwner`.
+- [ ] Every URL in the sitemap is either audited or explicitly excluded with a reason.
+- [ ] Every structured-data warning is reproduced with the exact bad value and the exact fix.
+- [ ] On-page findings from Step 2.7 use the `seo-audit` Issue / Impact / Evidence / Fix / Priority format.
+- [ ] The implementation prompt is self-contained and would not require this conversation to execute.
+
+---
+
+## Error Handling
+
+- If the Site Verification API returns `failedVerification`, do not retry blindly — surface the underlying reason (TXT not visible, wrong record, DNSSEC lag) and stop.
+- If `sites_add` fails with 403, the service account is not yet a verified owner — return to Phase 1.
+- If `sites_list` returns empty after a successful `sites_add`, the MCP cached an old session — instruct the user to restart Claude Code or the `gsc` MCP and retry.
+- If `search_analytics_query` returns no rows for a newly verified property, this is expected. Do not mark as failure.
+- If the Indexing API is suggested as a fix, decline it for non-`JobPosting`/`BroadcastEvent` content and explain why.
+- If a skill is unavailable, fall back to the next documented skill and note it in the report.