eai-cli 0.0.0-bootstrap.0

package/resources/gofer/commands/9_gofer_tests.md

@@ -0,0 +1,534 @@
+---
+name: 9_gofer_tests
+description: "Generate comprehensive test suites from four testing perspectives for a target component."
+title: "Gofer Tests"
+category: utility
+surfaces:
+  - claude
+  - claude-mirror
+  - copilot
+  - vscode
+  - codex
+  - gemini
+  - github-prompts
+  - agents-skills
+  - system-skills
+aliases: [gofer:tests]
+---
+---
+description:
+  Define acceptance test cases using DSL approach before or during
+  implementation
+---
+
+# Gofer Tests
+
+## 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 -->
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+---
+
+## When to Use This Command
+
+- **Test-First Development**: Define tests before writing implementation
+- **During Planning**: Add test definitions to plan.md
+- **During Implementation**: Create test scaffolds alongside code
+- **Before Validation**: Ensure comprehensive test coverage
+
+---
+
+## Core Principles (Agentic Testing Best Practices)
+
+### 1. Comment-First Approach
+
+Always start by writing test cases as structured comments before any
+implementation. This forces clear thinking about expected behavior.
+
+### 2. DSL at Every Layer
+
+All test code - setup, actions, assertions - must be written as readable DSL
+functions. No direct framework calls in test files.
+
+### 3. Implicit Given-When-Then
+
+Structure tests with blank lines separating setup, action, and assertion phases.
+Never use the words "Given", "When", or "Then" explicitly.
+
+### 4. Traceability to Requirements
+
+Every test case must trace back to a user story or acceptance criterion from
+spec.md.
+
+### 5. Follow Existing Patterns
+
+Study and follow existing test patterns, DSL conventions, and naming standards
+in the codebase.
+
+---
+
+## Step 1: Load Feature Context
+
+```bash
+.specify/scripts/bash/check-prerequisites.sh --json
+```
+
+Parse JSON for FEATURE_DIR, then load:
+
+- `spec.md` - User stories and acceptance criteria
+- `plan.md` - Technical architecture
+- `tasks.md` - Implementation tasks (if exists)
+
+---
+
+## Step 2: Research Existing Test Patterns
+
+**CRITICAL**: Before writing any test cases, spawn a research agent:
+
+```
+Task: subagent_type="codebase-pattern-finder", model="haiku"
+Prompt: "Find existing test files and patterns in this codebase.
+Identify:
+- Test file locations and naming conventions
+- DSL function patterns and naming conventions
+- Test organization patterns (describe blocks, test grouping)
+- Existing DSL functions for setup, actions, and assertions
+- Test framework being used (Jest, Vitest, Mocha, pytest, etc.)"
+```
+
+---
+
+## Step 3: Extract Test Requirements
+
+### 3.1 From User Stories
+
+For each user story in spec.md, extract:
+
+```markdown
+| User Story | Priority | Acceptance Criteria       | Test Cases Needed |
+| ---------- | -------- | ------------------------- | ----------------- |
+| US1        | P1       | User can login with email | TC001, TC002      |
+| US1        | P1       | Error on invalid creds    | TC003, TC004      |
+| US2        | P2       | Dashboard shows metrics   | TC005, TC006      |
+```
+
+### 3.2 Coverage Requirements
+
+Ensure tests cover:
+
+1. **Happy Paths** - Standard successful flows
+2. **Edge Cases** - Boundary conditions, unusual but valid inputs
+3. **Error Scenarios** - Invalid inputs, service failures, timeouts
+4. **Boundary Conditions** - Maximum/minimum values, empty states
+5. **Authorization** - Permission-based access scenarios
+
+---
+
+## Step 4: Define Test Cases
+
+### Test Case Structure
+
+```javascript
+// [Test Case ID]: [Test Case Name]
+// Traces to: [US-X AC-Y]
+//
+// setupFunction
+// anotherSetupFunction
+//
+// actionThatTriggersLogic
+//
+// expectationFunction
+// anotherExpectationFunction
+```
+
+### Structure Rules
+
+- **First line**: Test case ID and name
+- **Second line**: Traceability to user story/acceptance criterion
+- **Blank line**: Before setup
+- **Setup phase**: Functions that arrange test state (no blank lines between)
+- **Blank line**: Separates setup from action
+- **Action phase**: Function(s) that trigger the behavior under test
+- **Blank line**: Separates action from assertions
+- **Assertion phase**: Functions that verify expected outcomes
+
+---
+
+## Step 5: Naming Conventions
+
+### Setup Functions (Arrange)
+
+Describe state being created:
+
+- `userIsLoggedIn`, `cartHasThreeItems`, `databaseIsEmpty`
+- `createUser`, `seedDatabase`, `mockExternalAPI`
+
+### Action Functions (Act)
+
+Describe the event/action:
+
+- `userClicksCheckout`, `orderIsSubmitted`, `apiReceivesRequest`
+- `submitForm`, `sendRequest`, `processPayment`
+
+### Assertion Functions (Assert)
+
+Start with `expect`:
+
+- `expectOrderProcessed`, `expectUserRedirected`, `expectEmailSent`
+- `expectNoEmailSent`, `expectOrderNotCreated` (negative cases)
+
+---
+
+## Step 6: Generate Test Document
+
+Write to `{FEATURE_DIR}/test-cases.md`:
+
+````markdown
+---
+feature: [Feature Name]
+created: [ISO timestamp]
+spec: spec.md
+status: draft
+coverage:
+  user_stories: [N]/[Total]
+  acceptance_criteria: [N]/[Total]
+---
+
+# Test Cases: [Feature Name]
+
+## Test Coverage Matrix
+
+| User Story | Acceptance Criterion | Test Case(s) | Status  |
+| ---------- | -------------------- | ------------ | ------- |
+| US1        | AC1: User can login  | TC001, TC002 | Defined |
+| US1        | AC2: Error handling  | TC003, TC004 | Defined |
+| US2        | AC1: Dashboard       | TC005        | Defined |
+
+## Test Case Definitions
+
+### Happy Path Tests
+
+#### TC001: Successful Login with Valid Credentials
+
+Traces to: US1-AC1
+
+```javascript
+// TC001: Successful Login with Valid Credentials
+// Traces to: US1-AC1
+//
+// userExists({ email: 'test@example.com', password: 'valid' })
+//
+// userSubmitsLogin({ email: 'test@example.com', password: 'valid' })
+//
+// expectUserLoggedIn()
+// expectRedirectedToDashboard()
+// expectSessionCreated()
+```
+
+#### TC002: Login Remembers User Preference
+
+Traces to: US1-AC1
+
+```javascript
+// TC002: Login Remembers User Preference
+// Traces to: US1-AC1
+//
+// userExists({ email: 'test@example.com' })
+// rememberMeEnabled()
+//
+// userSubmitsLogin({ email: 'test@example.com', password: 'valid' })
+//
+// expectPersistentSessionCreated()
+// expectCookieSet('remember_token')
+```
+
+### Edge Case Tests
+
+#### TC003: Login with Maximum Length Password
+
+Traces to: US1-AC1
+
+```javascript
+// TC003: Login with Maximum Length Password
+// Traces to: US1-AC1
+//
+// userExists({ password: 'a'.repeat(128) })
+//
+// userSubmitsLogin({ password: 'a'.repeat(128) })
+//
+// expectUserLoggedIn()
+```
+
+### Error Scenario Tests
+
+#### TC004: Login with Invalid Credentials
+
+Traces to: US1-AC2
+
+```javascript
+// TC004: Login with Invalid Credentials
+// Traces to: US1-AC2
+//
+// userExists({ email: 'test@example.com', password: 'correct' })
+//
+// userSubmitsLogin({ email: 'test@example.com', password: 'wrong' })
+//
+// expectUserNotLoggedIn()
+// expectErrorMessage('Invalid credentials')
+// expectNoSessionCreated()
+```
+
+#### TC005: Login When Service Unavailable
+
+Traces to: US1-AC2
+
+```javascript
+// TC005: Login When Service Unavailable
+// Traces to: US1-AC2
+//
+// authServiceIsDown()
+//
+// userSubmitsLogin({ email: 'test@example.com', password: 'valid' })
+//
+// expectErrorMessage('Service temporarily unavailable')
+// expectRetryOption()
+```
+
+### Authorization Tests
+
+#### TC006: Unauthorized Access Attempt
+
+Traces to: US1-AC3
+
+```javascript
+// TC006: Unauthorized Access Attempt
+// Traces to: US1-AC3
+//
+// userIsNotAuthenticated()
+//
+// userNavigatesToProtectedRoute('/dashboard')
+//
+// expectRedirectedToLogin()
+// expectOriginalUrlPreserved()
+```
+
+## DSL Functions Required
+
+### Setup Functions (To Create)
+
+| Function              | Purpose                      | Exists? |
+| --------------------- | ---------------------------- | ------- |
+| `userExists()`        | Create test user in database | No      |
+| `authServiceIsDown()` | Mock auth service failure    | No      |
+| `rememberMeEnabled()` | Set remember me preference   | No      |
+
+### Action Functions (To Create)
+
+| Function             | Purpose                        | Exists? |
+| -------------------- | ------------------------------ | ------- |
+| `userSubmitsLogin()` | Simulate login form submission | No      |
+| `userNavigatesTo()`  | Navigate to URL                | Yes     |
+
+### Assertion Functions (To Create)
+
+| Function               | Purpose                    | Exists? |
+| ---------------------- | -------------------------- | ------- |
+| `expectUserLoggedIn()` | Verify user session exists | No      |
+| `expectErrorMessage()` | Verify error is displayed  | Yes     |
+| `expectRedirectedTo()` | Verify redirect occurred   | Yes     |
+
+## Implementation Notes
+
+### Test File Location
+
+Based on codebase patterns: `tests/integration/[feature]/`
+
+### Test Framework
+
+Using: [Jest/Vitest/Mocha/pytest] (from research)
+
+### DSL Implementation Location
+
+DSL functions should go in: `tests/helpers/` or `tests/dsl/`
+
+## Next Steps
+
+1. [ ] Create missing DSL functions
+2. [ ] Implement test scaffolds
+3. [ ] Run tests (expect failures)
+4. [ ] Implement feature code
+5. [ ] Verify tests pass
+````
+
+---
+
+## Step 7: Generate Test Scaffolds (Optional)
+
+If user wants actual test files, generate scaffolds:
+
+```javascript
+// tests/integration/[feature]/[feature].test.ts
+import { describe, test, expect } from 'vitest';
+import {
+  userExists,
+  userSubmitsLogin,
+  expectUserLoggedIn,
+  // ... other DSL functions
+} from '../../helpers/auth-dsl';
+
+describe('[Feature Name]', () => {
+  describe('US1: User Authentication', () => {
+    test('TC001: Successful Login with Valid Credentials', async () => {
+      // TC001: Successful Login with Valid Credentials
+      // Traces to: US1-AC1
+      //
+      // userExists({ email: 'test@example.com', password: 'valid' })
+      //
+      // userSubmitsLogin({ email: 'test@example.com', password: 'valid' })
+      //
+      // expectUserLoggedIn()
+      // expectRedirectedToDashboard()
+
+      await userExists({ email: 'test@example.com', password: 'valid' });
+
+      await userSubmitsLogin({ email: 'test@example.com', password: 'valid' });
+
+      await expectUserLoggedIn();
+      await expectRedirectedToDashboard();
+    });
+
+    // ... more tests
+  });
+});
+```
+
+---
+
+## Step 8: Update Tasks.md
+
+Add test implementation tasks to tasks.md:
+
+```markdown
+## Phase: Test Implementation
+
+- [ ] T0XX [P] Create DSL helper functions in tests/helpers/
+- [ ] T0XX [P] Implement test scaffolds for US1
+- [ ] T0XX [P] Implement test scaffolds for US2
+- [ ] T0XX Verify all tests fail initially (red phase)
+```
+
+---
+
+## Step 9: Report Completion
+
+```
+================================================================
+  TEST CASES DEFINED: [Feature Name]
+================================================================
+
+  Coverage:
+  - User Stories: [N]/[Total] covered
+  - Acceptance Criteria: [N]/[Total] covered
+  - Test Cases: [Total] defined
+
+  Test Types:
+  - Happy Path: [N] tests
+  - Edge Cases: [N] tests
+  - Error Scenarios: [N] tests
+  - Authorization: [N] tests
+
+  DSL Functions:
+  - Existing: [N] functions
+  - To Create: [N] functions
+
+  Output: {FEATURE_DIR}/test-cases.md
+
+  Next Steps:
+  1. Review test cases with stakeholders
+  2. Implement DSL functions
+  3. Create test scaffolds
+  4. Run tests (expect red)
+  5. Implement feature (turn green)
+
+================================================================
+```
+
+---
+
+## Test-First Workflow Integration
+
+### Before Implementation
+
+```
+/1_gofer_research  →  /2_gofer_specify  →  /3_gofer_plan
+                                                 ↓
+                                          /9_gofer_tests  ← Define tests here
+                                                 ↓
+                                          /4_gofer_tasks  →  /5_gofer_implement
+```
+
+### During Implementation
+
+After each task in `/5_gofer_implement`:
+
+1. Run relevant tests
+2. Verify behavior matches test expectations
+3. Mark test as passing in test-cases.md
+
+---
+
+## Observability Logging
+
+```bash
+.specify/scripts/bash/log-stage.sh 9_tests --complete --tokens [N] --compactions [N]
+```
+
+---
+
+## Key Rules
+
+- Every test must trace to a user story or acceptance criterion
+- Follow existing test patterns in the codebase
+- DSL functions must be readable as natural language
+- Tests should be independent and isolated
+- Include both positive and negative test cases
+- Document which DSL functions need to be created

package/resources/gofer/commands/gofer_bootstrap_workspace.md

@@ -0,0 +1,159 @@
+---
+name: gofer:bootstrap-workspace
+description: "Create or update the repo-owned Gofer scaffold for the current workspace."
+title: "Gofer Workspace Bootstrap"
+category: control
+surfaces:
+  - claude
+  - claude-mirror
+  - copilot
+  - vscode
+  - codex
+  - gemini
+  - github-prompts
+  - agents-skills
+  - system-skills
+---
+
+# Gofer Workspace Bootstrap
+
+## 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 -->
+
+## Guardrails
+
+- Preserve existing `.specify/specs/*` work.
+- Preserve existing `.specify/memory/constitution.md` if present.
+- Do **not** overwrite existing `AGENTS.md`, `CLAUDE.md`, or
+  `.github/copilot-instructions.md` by default. Create them only when missing.
+- Do **not** add repo-local assistant mirrors (`.claude/commands`,
+  `.agents/skills`, `.github/prompts`, `.gemini/`, etc.) unless the user
+  explicitly asks for them.
+
+## Step 1: Resolve The Workspace Root
+
+Use the current repository root. If you started inside a subdirectory, walk
+upward to the nearest directory containing `.git`, `package.json`,
+`pyproject.toml`, `go.mod`, `Cargo.toml`, or `.specify`.
+
+## Step 2: Select A Bootstrap Source
+
+Use the first source that exists:
+
+1. `~/plugins/eai-gofer`
+2. `./plugins/eai-gofer` when you are working in the Gofer repo itself
+3. Download the latest public bundle zip and extract it to a temporary folder:
+
+```bash
+curl -fsSL https://eai-tools.github.io/eai-gofer/releases/eai-gofer-agent-plugin-latest.zip \
+  -o /tmp/eai-gofer-agent-plugin-latest.zip
+rm -rf /tmp/eai-gofer-bootstrap
+mkdir -p /tmp/eai-gofer-bootstrap
+unzip -q /tmp/eai-gofer-agent-plugin-latest.zip -d /tmp/eai-gofer-bootstrap
+```
+
+When using the downloaded bundle, the source root is:
+
+```text
+/tmp/eai-gofer-bootstrap/eai-gofer
+```
+
+## Step 3: Run The Portable Bootstrap Script
+
+Prefer the scripted bootstrap from the selected source:
+
+```bash
+node "$SOURCE_ROOT/.specify/scripts/node/gofer-workspace-bootstrap.mjs" \
+  --workspace "$WORKSPACE_ROOT" \
+  --host "$GOFER_HOST"
+```
+
+Use the host value that matches the current client: `claude`, `codex`,
+`copilot`, or `gemini`.
+
+If the user explicitly asks for repo-local assistant mirrors as well, append:
+
+```bash
+--include-mirrors
+```
+
+The default bootstrap must create/update:
+
+- `.specify/commands/`
+- `.specify/templates/`
+- `.specify/scripts/bash/`
+- `.specify/scripts/node/`
+- `.specify/scripts/hooks/`
+- `.specify/scripts/powershell/`
+- `.specify/specs/`
+- `.specify/memory/`
+- `.specify/memory/gofer-model-policy.yaml` when missing
+- `.specify/.gofer-version`
+- `.specify/README.md`
+- Gofer runtime `.gitignore` entries
+
+And host-specific repo-owned files:
+
+- **Claude**: `AGENTS.md`, `CLAUDE.md`, `.claude/settings.json`
+- **Codex**: `AGENTS.md`
+- **Copilot**: `.github/copilot-instructions.md`
+- **Gemini**: no extra required repo-owned file beyond the core scaffold
+
+## Step 4: Re-Run The Workspace Check
+
+After bootstrap completes, run:
+
+```bash
+node .specify/scripts/node/gofer-workspace-check.mjs --host "$GOFER_HOST" --json
+```
+
+Report what changed and whether the workspace is now healthy.
+
+If the workspace is still stale because the repo-local scripts are older than
+the currently installed plugin bundle, explain that clearly and keep the
+selected source bundle as the truth for the update.
+
+## Step 5: Continue EAI App First-Run Setup When Needed
+
+If the user is building an EAI Platform app and Git, Node.js, npm, the EAI CLI,
+login, tenant access, or EAI app template readiness is still missing, run
+`/gofer:eai-first-run` next. Do not ask again when the workspace is healthy;
+only ask when an install, browser login, tenant selection, or `eai init` action
+is actually needed.
+
+## Step 6: Write The Workspace Bootstrap Report
+
+Write the artifact only to `.specify/logs/workspace-bootstrap-report.md`.
+
+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 workspace bootstrap report must contain these sections:
+
+- `## Provenance`
+- `## Workspace Root`
+- `## Bootstrap Source`
+- `## Host Policy`
+- `## Changes Applied`
+- `## Post-Check`