eai-cli 0.0.0-bootstrap.0

package/resources/gofer/agents-skills/gofer_diagnose/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: gofer:diagnose
+description: "Run a reproduce-minimize-instrument-fix loop for bugs and failing tests."
+---
+
+## Workspace Preflight
+
+Before doing stage/helper work:
+
+1. Resolve the repository root.
+2. Check the core Gofer sentinels:
+   - `.specify/.gofer-version`
+   - `.specify/commands/0_gofer_start.md`
+   - `.specify/templates/spec-template.md`
+   - `.specify/templates/loop-contract-template.json`
+   - `.specify/templates/working-backwards-prfaq-template.md`
+   - `.specify/templates/business-owner-summary-template.md`
+   - `.specify/templates/cto-architecture-summary-template.md`
+   - `.specify/templates/ciso-security-summary-template.md`
+   - `.specify/templates/stakeholder-review-index-template.md`
+   - `.specify/scripts/bash/create-new-feature.sh`
+   - `.specify/scripts/node/parse-stage-command.mjs`
+   - `.specify/scripts/node/gofer-loop-audit.mjs`
+   - `.specify/scripts/hooks/post-tool-use.mjs`
+   - `.specify/scripts/powershell/install-optional-tools.ps1`
+   - `.specify/templates/gofer-model-policy.yaml`
+   - `.specify/memory/gofer-model-policy.yaml`
+   - `.specify/specs/`
+   - `.specify/memory/`
+3. Check host-specific repo-owned files when relevant:
+   - Claude: `AGENTS.md`, `CLAUDE.md`, `.claude/settings.json`
+   - Codex: `AGENTS.md`
+   - Copilot: `.github/copilot-instructions.md`
+   - VS Code extension mirrors Claude/Copilot/Gemini resources itself and should still keep the core scaffold healthy
+4. If the repo already has the workspace checker script, prefer running:
+   - `node .specify/scripts/node/gofer-workspace-check.mjs --host codex --json`
+5. If the workspace is missing or stale, ask exactly:
+   - **"This repo is missing or stale for Gofer. Initialize/update it now?"**
+6. If the user says yes, run the Gofer workspace bootstrap helper and then resume this command from the top.
+7. If the user says no, stop and explain that Gofer stage/helper work depends on the repo-owned scaffold.
+
+
+# Gofer Diagnose
+
+## EAI Platform Session Preflight
+
+Before any Gofer stage/helper command does pipeline work:
+
+1. Treat durable delivery as EAI Platform delivery by default, with Azure second
+   and every other stack only by explicit exception.
+2. Run `eai whoami` and confirm the EAI CLI is installed, the user is logged in,
+   and an active tenant is visible.
+3. If `eai` is missing, `eai whoami` fails, the token is expired, or no active
+   tenant is available, stop and run `/gofer:eai-first-run` or ask the user to
+   approve login/setup before continuing.
+4. For EAI app delivery, do not continue into research, specification, planning,
+   tasks, implementation, or validation until
+   `.specify/specs/{feature}/eai-preflight.md` records login, tenant, template,
+   app-readiness, and next-action evidence.
+5. Do not write tokens, secrets, private tenant IDs, or local `.env` values into
+   Gofer artifacts; record only product-safe readiness status and evidence.
+
+## Token And Cost Policy
+<!-- gofer:token-cost-policy:start -->
+
+Before spawning agents, calling tools, or loading large files:
+
+1. Treat `.specify/memory/gofer-model-policy.yaml` as the repo-owned source of truth for simple, medium, hard, and arbiter model routing. If it is missing, run `/gofer:bootstrap-workspace` before continuing.
+2. Use the cheapest capable model first.
+   - Claude: Haiku for scouting/extraction; Sonnet for normal implementation, synthesis, validation, and security; Opus for high-risk arbitration or release-critical failures.
+   - Codex/OpenAI: GPT mini for simple coding; GPT nano only for locate/classify/summarize/mechanical work; GPT-5.3-Codex or flagship GPT for tool-heavy coding, architecture, and release-critical validation.
+   - Gemini: Flash-Lite for cheap large-context scan/summarize; Flash for default research synthesis; Pro for large-context architecture or high-risk arbitration.
+   - Copilot: prefer Auto for simple and default work; ask the user before choosing a paid/high-tier picker model for hard security, architecture, or release gates.
+3. Keep raw tool output out of the main conversation context. Save stable findings to `.specify/specs/{feature}/context-bundle.md`, then work from summaries.
+4. Use provider prompt/context caching only for stable, non-secret prefixes: Gofer scaffold, AGENTS/CLAUDE/Copilot instructions, constitution, repo map, stage contracts, and validation rubric.
+5. Before continuing after large research, planning, implementation, or validation bursts, checkpoint the durable artifacts and compact/clear/resume context when the host supports it.
+6. Escalate model tier only when a cheaper pass is low-confidence, contradictory, security-sensitive, or blocking release quality.
+<!-- gofer:token-cost-policy:end -->
+
+Run a structured reproduce-minimize-instrument-fix investigation and write the
+results to `.specify/specs/{feature}/diagnose-report.md`.
+
+Use this when an implementation, test, or integration is failing and you need a
+portable, evidence-backed debugging record that stays inside the feature
+directory.
+
+When you run this helper:
+
+1. Start from the actual failure evidence already present in the session:
+   failing output, stack traces, logs, screenshots, or a concrete bug report.
+2. Reproduce the failure as directly as possible.
+3. Minimize the problem to the smallest reliable failing slice.
+4. Instrument the likely fault boundaries to prove or disprove hypotheses.
+5. Record the recommended fix path without inventing evidence.
+6. Write the artifact only to
+   `.specify/specs/{feature}/diagnose-report.md`.
+7. If the target file already exists, replace it and prepend a regeneration note
+   such as `<!-- regenerated at [ISO timestamp] -->`.
+8. Include the minimum provenance schema:
+   - `GeneratedAt`
+   - `SourceCommandId`
+   - `SourceInputs`
+   - `OverwriteNoticeWhenApplicable`
+
+The generated diagnose report must contain these sections:
+
+- `## Provenance`
+- `## Reproduce`
+- `## Minimize`
+- `## Instrument`
+- `## Fix`
+
+Keep the content Gofer-owned. Do not copy upstream Matt Pocock skill text
+verbatim.

package/resources/gofer/agents-skills/gofer_eai_first_run/SKILL.md

@@ -0,0 +1,397 @@
+---
+name: gofer:eai-first-run
+description: "Prepare a new machine or repo for the first EAI Gofer app build."
+---
+
+## Token And Cost Policy
+<!-- gofer:token-cost-policy:start -->
+
+Before spawning agents, calling tools, or loading large files:
+
+1. Treat `.specify/memory/gofer-model-policy.yaml` as the repo-owned source of truth for simple, medium, hard, and arbiter model routing. If it is missing, run `/gofer:bootstrap-workspace` before continuing.
+2. Use the cheapest capable model first.
+   - Claude: Haiku for scouting/extraction; Sonnet for normal implementation, synthesis, validation, and security; Opus for high-risk arbitration or release-critical failures.
+   - Codex/OpenAI: GPT mini for simple coding; GPT nano only for locate/classify/summarize/mechanical work; GPT-5.3-Codex or flagship GPT for tool-heavy coding, architecture, and release-critical validation.
+   - Gemini: Flash-Lite for cheap large-context scan/summarize; Flash for default research synthesis; Pro for large-context architecture or high-risk arbitration.
+   - Copilot: prefer Auto for simple and default work; ask the user before choosing a paid/high-tier picker model for hard security, architecture, or release gates.
+3. Keep raw tool output out of the main conversation context. Save stable findings to `.specify/specs/{feature}/context-bundle.md`, then work from summaries.
+4. Use provider prompt/context caching only for stable, non-secret prefixes: Gofer scaffold, AGENTS/CLAUDE/Copilot instructions, constitution, repo map, stage contracts, and validation rubric.
+5. Before continuing after large research, planning, implementation, or validation bursts, checkpoint the durable artifacts and compact/clear/resume context when the host supports it.
+6. Escalate model tier only when a cheaper pass is low-confidence, contradictory, security-sensitive, or blocking release quality.
+<!-- gofer:token-cost-policy:end -->
+
+
+# EAI Gofer First Run
+
+Use this command when the user is starting their first EAI Platform app, when
+`/0_gofer_start` is unavailable in a new repository, or when an EAI app
+build reaches the Gofer pipeline before the local machine, workspace, tenant, or
+EAI app template is ready.
+
+This command is intentionally allowed to run before `.specify/` exists.
+
+## Non-Negotiables
+
+- Ask before every install, admin action, browser login, destructive file
+  change, or remote tenant/app change.
+- Never print, store, or commit tokens, secrets, full `.env.local` values,
+  private tenant payloads, or private platform topology.
+- Prefer existing tools over reinstalling. Keep working Git, Node.js, npm, and
+  EAI CLI installations.
+- Do not scaffold over a non-empty repo silently.
+- Use the EAI Platform app template first, Azure second, and non-EAI stacks only
+  by explicit exception.
+- In GitHub Codespaces, avoid `sudo` or host-level package installs unless the
+  user explicitly approves. Prefer the prebuilt devcontainer and user-level npm.
+
+## Step 1: Identify Host, OS, Shell, And Workspace
+
+Detect and report:
+
+- Host: Claude Code, Codex, GitHub Copilot, Gemini, VS Code, GitHub Codespaces,
+  or unknown.
+- OS: macOS, Linux, Windows, or Codespaces Linux.
+- Shell: bash/zsh, PowerShell, cmd, or unknown.
+- Workspace root: current folder, opened editor workspace, Codespace checkout,
+  or a folder the user wants to create.
+
+If no suitable folder is open, ask the user where the project should live. If
+the host can create the folder, ask approval and create it. If not, give exact
+click/command instructions and continue after the folder is open.
+
+## Step 2: Check Developer Prerequisites
+
+Run only safe read/check commands first:
+
+| Tool    | POSIX check                       | PowerShell check                         |
+| ------- | --------------------------------- | ---------------------------------------- |
+| Git     | `git --version`                   | `git --version`                          |
+| Node.js | `node --version`                  | `node --version`                         |
+| npm     | `npm --version`                   | `npm --version`                          |
+| EAI CLI | `eai --version`                   | `eai --version`                          |
+| Registry | `npm config get @eai-tools:registry` | `npm config get @eai-tools:registry` |
+
+If Git, Node.js, or npm is missing, ask before installing. Use the least
+surprising platform path:
+
+| Platform            | Preferred install path                                                                 |
+| ------------------- | --------------------------------------------------------------------------------------- |
+| macOS               | Use Homebrew if already installed; otherwise use the official Git/Node installer path.  |
+| Linux               | Prefer existing devcontainer tools; otherwise detect `apt`, `dnf`, `yum`, or `zypper`. |
+| Windows             | Prefer `winget`; fall back to the official Git for Windows and Node.js installers.      |
+| GitHub Codespaces   | Prefer preinstalled tools and user-level npm; avoid host-level package installs.        |
+
+For Windows, use PowerShell-safe syntax. Do not emit POSIX-only shell redirection
+or assume Git Bash exists unless it was detected.
+
+## Step 3: Install Or Update EAI CLI
+
+If `eai` is missing, or if the user asks to update it, ask for approval and run:
+
+```bash
+npm config set @eai-tools:registry https://eai-tools.github.io/eai/registry/ --location=user
+npm install -g @eai-tools/cli
+eai --version
+```
+
+Use the same commands in PowerShell. Do not edit `.npmrc` by shell redirection.
+
+If the scoped registry already equals
+`https://eai-tools.github.io/eai/registry/`, do not rewrite it. If it points
+somewhere else, show the current value and ask before changing it.
+
+If `eai` is already installed, run:
+
+```bash
+eai update --check
+```
+
+If an update is available, explain the currently installed version versus the
+latest available version and ask before running `eai update`.
+
+If install fails, stop EAI app delivery and give the user the exact failed
+command, the public setup link, and the account requirement. Continue only if
+the user explicitly chooses a non-EAI path.
+
+## Step 4: Discover EAI CLI Capabilities
+
+Run:
+
+```bash
+eai --describe
+```
+
+If advertised, also run:
+
+```bash
+eai agent guide --format json
+```
+
+Prefer commands and options advertised by the installed CLI over remembered
+syntax. Use JSON only where the CLI advertises it. Record a safe summary in the
+first-run report.
+
+When any later `eai` command fails, use the CLI's error guidance before
+inventing a workaround:
+
+```bash
+eai errors explain <code-or-reason> --format json
+```
+
+If `eai errors explain` is unavailable, use the installed Gofer fallback catalog
+at `.specify/references/platform/eai-error-catalog.yaml` once the repo exists,
+or report that live EAI guidance is unavailable and stop before mutating
+tenant/app state. Always run read-only diagnostics before mutating fixes.
+
+For tenant member/admin operations, if `eai user invite` fails with
+`EXTERNAL_SERVICE_ERROR`, a 5xx response, or
+`user_invite_external_service_existing_member`, check for an existing direct
+member with:
+
+```bash
+eai user list --tenant <tenant-id> --search <email> --format json
+```
+
+Use role repair only after the existing member ID is verified and the user
+approves the role change:
+
+```bash
+eai user role set --tenant <tenant-id> --member-id <member-id> --role tenant-admin --format json
+```
+
+Then verify the read-back and tell the affected app user to sign out and sign
+back in because Auth.js session or JWT role data may be cached.
+
+Specifically note whether the installed CLI advertises the commands needed for:
+
+- app scaffolding via `eai init`
+- tenant selection via `eai tenant select`
+- app enrollment via `eai app`
+- resource schema discovery via `eai resources schema`
+- workflow readiness via `eai workflow readiness`
+- Entra app registration and redirect URI provisioning via `eai provision entra`
+- project drift checks via `eai template check`
+- Gofer drift checks via `eai gofer refresh --check`
+- UI block discovery via `eai blocks`
+- AI-agent guidance via `eai agent guide`
+- error recovery guidance via `eai errors explain`
+
+## Step 5: Login, Tenant, And Account Readiness
+
+Run:
+
+```bash
+eai whoami
+eai tenant list --format json
+```
+
+If not logged in or the token is expired, ask before running:
+
+```bash
+eai login
+```
+
+After login, list tenants again. If more than one tenant is available, help the
+user choose the correct one and run the advertised equivalent of:
+
+```bash
+eai tenant select <tenant-slug-or-id>
+```
+
+Require at least one usable tenant membership before EAI app delivery. Prefer a
+tenant-admin/operator-capable role because app enrollment and provisioning are
+tenant-scoped actions. If no tenant is available, tell the user they need an EAI
+Platform account and tenant access before Gofer can build an app.
+
+## Step 6: Confirm Project Folder And Name
+
+Before `eai init`, ask whether the current folder/workspace is the right place.
+If the user wants a new sibling or child folder, create it only after approval.
+
+Ask for the project display name. If the user gives a plain-language name,
+propose a lowercase kebab-case CLI name and confirm it before continuing.
+
+Collect or confirm:
+
+- App display name
+- Lowercase kebab-case app/project name
+- One-sentence business description
+- Active tenant
+- Whether starter defaults should be kept
+
+## Step 7: Initialize The EAI App Template
+
+Detect existing template markers before scaffolding:
+
+- `src/eai.config/object-types.ts`
+- `src/eai.config/register.ts`
+- `.env.example`
+- `.npmrc`
+- `package.json`
+
+If the repo already looks like an EAI app, run `eai verify` and continue with
+the existing project. If the installed CLI advertises them, also run:
+
+```bash
+eai template check --format json
+eai gofer refresh --check --format json
+```
+
+If `eai verify`, `eai template check`, or `eai doctor --check-updates`
+returns `E001` or reports "Not in an EAI project", treat the repo as not yet
+initialized from the EAI app template and explain that clearly.
+
+If this is an empty or approved target folder, ask for final confirmation and
+run the advertised equivalent of:
+
+```bash
+eai init <project-name> --skip-prompts --company-tenant <active-tenant-id>
+```
+
+If the CLI requires additional safe answers, gather them first. If the repo is
+non-empty and not an EAI app, ask whether to initialize a new sibling EAI app
+directory or stop.
+
+## Step 8: Recover Known Entra Redirect Mismatches
+
+If the user provides a browser sign-in error, auth callback log, or deployment
+log containing `AADSTS50011`, "reply URL specified in the request does not
+match", "redirect URI", `redirect_uri`, or
+`/api/auth/callback/microsoft-entra-id`, treat it as an EAI identity
+provisioning recovery before giving manual Azure Portal instructions.
+
+Do this sequence:
+
+```bash
+eai whoami
+eai tenant list --format json
+```
+
+If the active tenant is missing or wrong, help the user choose the right tenant
+and run the advertised equivalent of:
+
+```bash
+eai tenant select <tenant-slug-or-id>
+```
+
+Use the failing browser log to confirm the callback route in the active session,
+for example:
+
+```text
+https://<host>/api/auth/callback/microsoft-entra-id
+```
+
+Record only the redacted route pattern and recovery status in Gofer artifacts.
+Keep the full callback URI in the terminal/session or user-approved local notes
+only.
+
+Ask before changing tenant-scoped identity configuration, then run the
+advertised equivalent of:
+
+```bash
+eai provision entra --force --redirect-uri <confirmed-callback-uri>
+```
+
+Use `--debug` only when the user explicitly approves it, and redact private
+hostnames, tenant IDs, client IDs, tokens, and raw debug output before writing
+any report.
+
+After the command succeeds, retry the sign-in flow and confirm the authorize
+request uses the same registered `redirect_uri`. If the mismatch persists,
+check whether `AUTH_ENTRA_CLIENT_ID` or `ENTRA_CLIENT_ID` points to a different
+app registration than the one EAI provisioned. Never record client secrets,
+tokens, or `.env.local` values in the first-run report.
+
+## Step 9: Confirm Gofer Scaffold And Workspace Commands
+
+After `eai init`, verify Gofer files exist:
+
+- `.specify/.gofer-version`
+- `.specify/commands/0_gofer_start.md`
+- `.specify/templates/spec-template.md`
+- `.specify/scripts/node/gofer-workspace-check.mjs`
+- `.specify/memory/gofer-model-policy.yaml`
+- `AGENTS.md` or the host-specific instruction file
+
+If the Gofer scaffold is missing or stale, run `/gofer:bootstrap-workspace`
+using the current host policy, then rerun:
+
+```bash
+node .specify/scripts/node/gofer-workspace-check.mjs --host auto --json
+```
+
+If the current host cannot run slash commands yet, use the installed plugin
+bundle or downloaded public bundle as the bootstrap source described by
+`/gofer:bootstrap-workspace`.
+
+## Step 9: Open Or Attach The Created Project
+
+Make sure the active host is working in the initialized EAI app folder:
+
+- VS Code: open the folder in the current or a new VS Code window when `code`
+  is available; otherwise give exact UI steps.
+- Codex: show the absolute folder path and ask the user to open that folder as
+  the active Codex workspace if the host cannot switch automatically.
+- Claude Code: show the absolute folder path and ask the user to attach/open it
+  if the host cannot switch automatically.
+- Gemini/Copilot in VS Code: ensure the VS Code workspace is the initialized app
+  folder before starting Gofer.
+- GitHub Codespaces: keep the current Codespace workspace unless the project was
+  created in a subfolder; then `cd` into it and report the path.
+
+## Step 10: Write The First-Run Report
+
+Write only to `.specify/logs/eai-first-run-report.md`. If `.specify/` does not
+exist yet, create the report after `eai init` or after Gofer bootstrap.
+
+If the target file already exists, replace it and prepend a regeneration note
+such as `<!-- regenerated at [ISO timestamp] -->`.
+
+Include the minimum provenance schema:
+
+- `GeneratedAt`
+- `SourceCommandId`
+- `SourceInputs`
+- `OverwriteNoticeWhenApplicable`
+
+The generated first-run report must contain these sections:
+
+- `## Provenance`
+- `## Workspace Root`
+- `## Environment Check`
+- `## EAI CLI`
+- `## Tenant And Login`
+- `## Template Readiness`
+- `## Drift And Recovery`
+- `## Next Action`
+
+Each section should include:
+
+- Host, OS, shell, workspace root, and prerequisite tool versions
+- Git, Node.js, npm, and EAI CLI versions
+- EAI registry status
+- EAI CLI release status from `eai update --check`
+- EAI CLI capability source (`eai --describe` timestamp)
+- EAI capability inventory for init, tenant, app, resources, workflow,
+  template, Gofer-refresh, and blocks commands
+- Login status without tokens
+- Tenant readiness without private payloads
+- Template readiness
+- Template/Gofer drift status, the next recovery command, and any `E001`
+  explanation
+- Gofer scaffold readiness and project path
+- Next action
+
+## Step 11: Start The Pipeline
+
+When the app folder, EAI CLI, login, tenant, EAI template, and Gofer scaffold are
+ready, tell the user to start:
+
+```text
+/0_gofer_start <what you want to build>
+```
+
+If `/0_gofer_start` is still unknown after the plugin is installed and the
+repo is bootstrapped, explain that the host has not loaded the Gofer plugin or
+repo commands yet. Give the host-specific install/update command from the Gofer
+README, then retry this command after the host reloads.