eai-cli 0.0.0-bootstrap.0

package/resources/gofer/specify-commands/gofer_check_workspace.md

@@ -0,0 +1,130 @@
+---
+name: gofer:check-workspace
+description: "Check whether this repo is initialized for Gofer and explain any missing or stale scaffold."
+title: "Gofer Workspace Check"
+category: control
+surfaces:
+  - claude
+  - claude-mirror
+  - copilot
+  - vscode
+  - codex
+  - gemini
+  - github-prompts
+  - agents-skills
+  - system-skills
+---
+
+# Gofer Workspace Check
+
+## 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 -->
+
+## Step 1: Resolve The Workspace Root
+
+Use the current working directory unless you are already inside `.specify/` or a
+subdirectory. If needed, walk upward to the nearest directory containing one of:
+
+- `.git`
+- `package.json`
+- `pyproject.toml`
+- `go.mod`
+- `Cargo.toml`
+- `.specify`
+
+## Step 2: Check The Core Gofer Sentinels
+
+Inspect these paths relative to the workspace root:
+
+- `.specify/.gofer-version`
+- `.specify/commands/0_gofer_start.md`
+- `.specify/templates/spec-template.md`
+- `.specify/scripts/bash/create-new-feature.sh`
+- `.specify/scripts/node/parse-stage-command.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/`
+- `.specify/memory/gofer-model-policy.yaml` (create with `/gofer:bootstrap-workspace` if missing)
+
+## Step 3: Check Host-Specific Files
+
+Check the current host's required repo-owned files:
+
+- **Claude**: `AGENTS.md`, `CLAUDE.md`, `.claude/settings.json`
+- **Codex**: `AGENTS.md`
+- **Copilot**: `.github/copilot-instructions.md`
+- **Gemini**: no additional required repo-owned files beyond the core scaffold
+
+## Step 4: Prefer Scripted Evidence When Available
+
+If the repo already has the Gofer workspace scripts, run the checker for the
+current host and report the JSON result. Use the host value that matches the
+client you are currently in: `claude`, `codex`, `copilot`, or `gemini`.
+
+```bash
+node .specify/scripts/node/gofer-workspace-check.mjs --host "$GOFER_HOST" --json
+```
+
+If that script is missing, perform the equivalent manual path checks yourself
+and summarize the result in the same categories:
+
+- `healthy`
+- `missing`
+- `stale`
+
+Treat the workspace as `stale` when `.specify/.gofer-version` is present but
+does not match the installed Gofer/plugin version you are currently running.
+
+## Step 5: Write The Workspace Check Report
+
+Write the artifact only to `.specify/logs/workspace-check-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 check report must contain these sections:
+
+- `## Provenance`
+- `## Workspace Root`
+- `## Core Scaffold`
+- `## Host Requirements`
+- `## Status`
+- `## Recommendation`
+
+## Step 6: Report And Ask Once If Repair Is Needed
+
+If the workspace is healthy, say so briefly and continue.
+
+If the workspace is missing or stale, ask exactly:
+
+**"This repo is missing or stale for Gofer. Initialize/update it now?"**
+
+If the user says **yes**, run `/gofer:bootstrap-workspace` next.
+
+If the user says **no**, stop. Explain that Gofer stage/helper commands depend
+on the repo-owned scaffold and should not continue until the repo is initialized
+or updated.

package/resources/gofer/specify-commands/gofer_constitution.md

@@ -0,0 +1,588 @@
+---
+name: gofer_constitution
+description: "Create or update project constitution with coding principles and guidelines."
+title: "Gofer Constitution"
+category: utility
+surfaces:
+  - claude
+  - claude-mirror
+  - copilot
+  - vscode
+  - codex
+  - gemini
+  - github-prompts
+  - agents-skills
+  - system-skills
+aliases: [gofer:constitution]
+---
+---
+description:
+  Create or update project constitution with coding principles and guidelines
+---
+
+# Gofer Constitution
+
+## 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 -->
+
+## Source-of-Truth and Codex Distribution (FR-001, FR-010)
+
+The Gofer constitution lives at `.specify/memory/constitution.md` and is the
+authoritative reference for cross-cutting concerns the entire pipeline must
+respect.
+
+Two invariants the constitution MUST document and this command MUST preserve
+when updating:
+
+1. **Source-of-truth (FR-001)**: All stage commands derive from canonical files
+   at `.specify/commands/<stage>.md` — YAML frontmatter (name, description ≤140
+   chars, surfaces, args) plus Markdown body. The generator at
+   `.specify/scripts/node/generate-commands.mjs` emits to every CLI surface
+   (`.claude/commands/`, `extension/resources/copilot-prompts/`,
+   `.github/prompts/`, `.gemini/commands/gofer/`, `.agents/skills/`, and the
+   legacy compatibility mirror `.system/skills/`). Hand-edits on emitted files
+   are rejected by the generator without `--force-emit`. **Never bypass the
+   source-of-truth.**
+
+2. **Codex distribution path (FR-010)**: Codex discovers skills at
+   `.agents/skills/` (one folder per skill:
+   `.agents/skills/<stage>/SKILL.md`). This is NOT the same as
+   `.claude/skills/`, and it is the only repo-local path Codex should rely on
+   for normal Gofer installs. The constitution MUST capture that distinction
+   explicitly so future authors do not conflate the two paths or recreate
+   duplicate global Gofer bundles. The official Codex disable knob is a
+   per-skill `[[skills.config]]` entry with a `path = "/full/path/to/skill"`
+   plus `enabled = false` in `~/.codex/config.toml`; there is no global
+   skill-budget percentage key (FR-011).
+
+When updating the constitution, ensure both sections survive the edit pass.
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+---
+
+## Why Constitution Matters for Agentic Coding
+
+1. **Consistency Across Sessions**: Agents follow the same rules every time
+2. **Memory Persistence**: Decisions survive context window limits
+3. **Team Alignment**: All agents (and humans) follow same guidelines
+4. **Quality Gates**: Automatic validation against principles
+5. **Knowledge Capture**: Learnings from past work inform future work
+
+---
+
+## When to Use This Command
+
+- **Project Setup**: Initialize constitution for new project
+- **Post-Implementation Learning**: Capture decisions from completed features
+- **Standards Update**: Add new conventions or patterns
+- **Onboarding**: Document expectations for new team members/agents
+
+---
+
+## Step 1: Check Existing Constitution
+
+```bash
+# Check if constitution exists
+if [ -f ".specify/memory/constitution.md" ]; then
+  echo "Constitution exists - will update"
+else
+  echo "No constitution - will create"
+fi
+```
+
+Read existing constitution if present.
+
+---
+
+## Step 2: Gather Principles
+
+### If Creating New Constitution
+
+Ask the user using AskUserQuestion:
+
+```
+I'll help you create a project constitution. What areas would you like to define?
+
+1. Coding Standards (naming, formatting, patterns)
+2. Architecture Principles (structure, dependencies, layering)
+3. Testing Requirements (coverage, types, conventions)
+4. Security Guidelines (auth, data handling, secrets)
+5. Performance Standards (targets, monitoring, optimization)
+6. Documentation Requirements (comments, READMEs, ADRs)
+7. All of the above (I'll ask about each)
+```
+
+### If Updating Existing Constitution
+
+Ask:
+
+```
+What would you like to update in the constitution?
+
+1. Add new principle(s)
+2. Modify existing principle(s)
+3. Remove outdated principle(s)
+4. Add architectural decision record (ADR)
+5. Update coding standards
+6. Review and validate current constitution
+```
+
+---
+
+## Step 3: Research Codebase Patterns
+
+Before writing principles, understand current codebase:
+
+```
+Task: subagent_type="codebase-pattern-finder", model="haiku"
+Prompt: "Analyze the codebase for existing patterns and conventions.
+Find:
+- Naming conventions (files, variables, functions)
+- Code organization patterns
+- Testing patterns and conventions
+- Error handling patterns
+- Documentation style
+Report patterns that should be formalized as principles."
+```
+
+---
+
+## Step 4: Generate Constitution
+
+Write to `.specify/memory/constitution.md`:
+
+````markdown
+---
+version: 1.0
+created: [ISO date]
+updated: [ISO date]
+status: active
+---
+
+# Project Constitution
+
+> This document defines the principles and standards that guide all development
+> work in this project. AI agents and human developers MUST follow these
+> guidelines.
+
+## Core Principles
+
+### P1: [Principle Name]
+
+**Statement**: [Clear, actionable statement]
+
+**Rationale**: [Why this matters]
+
+**Examples**:
+
+- Good: [Example of following this principle]
+- Bad: [Example of violating this principle]
+
+**Enforcement**: [How this is validated]
+
+### P2: [Principle Name]
+
+...
+
+## Coding Standards
+
+### Naming Conventions
+
+| Element   | Convention        | Example           |
+| --------- | ----------------- | ----------------- |
+| Files     | [kebab/camel/etc] | `user-service.ts` |
+| Classes   | [PascalCase]      | `UserService`     |
+| Functions | [camelCase]       | `getUserById`     |
+| Constants | [UPPER_SNAKE]     | `MAX_RETRY_COUNT` |
+| Variables | [camelCase]       | `userData`        |
+
+### Code Organization
+
+```
+src/
+├── [layer]/           # [Description]
+│   ├── [sublayer]/    # [Description]
+│   └── index.ts       # Public exports only
+├── types/             # Shared type definitions
+├── utils/             # Shared utilities
+└── index.ts           # Main entry point
+```
+````
+
+### Import Order
+
+1. External packages (node_modules)
+2. Internal absolute imports
+3. Relative imports
+4. Type imports (if separate)
+
+### Error Handling
+
+- MUST: [Error handling requirement]
+- MUST NOT: [Anti-pattern to avoid]
+- SHOULD: [Best practice]
+
+## Architecture Principles
+
+### Dependency Direction
+
+```
+UI → Application → Domain → Infrastructure
+     ↓
+   Never depend on layers above
+```
+
+### Component Boundaries
+
+| Component | May Depend On      | Must Not Depend On |
+| --------- | ------------------ | ------------------ |
+| UI        | Application, Types | Domain, Infra      |
+| Domain    | Types              | Anything else      |
+
+### State Management
+
+- [Principle about state]
+- [Where state should live]
+- [How state should flow]
+
+## Testing Requirements
+
+### Coverage Targets
+
+| Type        | Target    | Current  |
+| ----------- | --------- | -------- |
+| Unit        | 80%       | [X]%     |
+| Integration | 60%       | [X]%     |
+| E2E         | Key flows | [status] |
+
+### Test Patterns
+
+- Use DSL functions for readability
+- Follow Arrange-Act-Assert structure
+- One assertion concept per test
+- Test behavior, not implementation
+
+### Required Tests
+
+- [ ] All public API functions
+- [ ] All error handling paths
+- [ ] All edge cases identified in specs
+
+## Security Guidelines
+
+### Authentication/Authorization
+
+- [Requirement]
+- [Pattern to follow]
+
+### Data Handling
+
+- NEVER: Store secrets in code
+- NEVER: Log sensitive data
+- ALWAYS: Validate external input
+- ALWAYS: Use parameterized queries
+
+### Secrets Management
+
+- Location: [Where secrets go]
+- Format: [How to reference]
+- Rotation: [Policy]
+
+## Performance Standards
+
+### Response Time Targets
+
+| Operation  | Target  | Critical Path? |
+| ---------- | ------- | -------------- |
+| API call   | < 200ms | Yes            |
+| Page load  | < 2s    | Yes            |
+| Background | < 30s   | No             |
+
+### Resource Limits
+
+- Memory: [Limit]
+- CPU: [Limit]
+- Bundle size: [Limit]
+
+## Documentation Requirements
+
+### Code Comments
+
+- Document "why", not "what"
+- Required for: complex logic, workarounds, non-obvious decisions
+- Not required for: self-explanatory code
+
+### API Documentation
+
+- All public functions must have JSDoc/docstrings
+- Include: description, parameters, return value, errors
+
+### Architecture Decision Records
+
+When making significant decisions, create ADR in `.specify/memory/decisions/`.
+
+## Quality Gates
+
+These checks MUST pass before code is considered complete:
+
+```bash
+# Automated checks
+npm run lint        # Zero errors
+npm run typecheck   # Zero errors
+npm test            # All pass
+npm run build       # Successful
+
+# Manual checks
+- [ ] Code review approved
+- [ ] Tests cover new functionality
+- [ ] Documentation updated
+```
+
+## Violations and Exceptions
+
+### How to Handle Violations
+
+1. **Accidental**: Fix before committing
+2. **Intentional**: Document exception with ADR
+3. **Systemic**: Propose constitution amendment
+
+### Exception Format
+
+When violating a principle intentionally:
+
+```typescript
+// CONSTITUTION EXCEPTION: P3 - [Principle Name]
+// Reason: [Why violation is necessary]
+// ADR: .specify/memory/decisions/NNN-exception.md
+// TODO: [Plan to resolve, if any]
+```
+
+## Version History
+
+| Version | Date   | Changes              | Author |
+| ------- | ------ | -------------------- | ------ |
+| 1.0     | [date] | Initial constitution | Claude |
+
+````
+
+---
+
+## Step 5: Create Decision Record Template
+
+Ensure `.specify/memory/decisions/` exists and has template:
+
+```markdown
+# .specify/memory/decisions/000-template.md
+
+---
+id: NNN
+title: '[Decision Title]'
+status: [proposed|accepted|deprecated|superseded]
+date: [ISO date]
+deciders: [who made this decision]
+---
+
+# [Decision Title]
+
+## Context
+
+[What is the issue we're addressing?]
+
+## Decision
+
+[What is the change we're making?]
+
+## Consequences
+
+### Positive
+
+- [Benefit 1]
+- [Benefit 2]
+
+### Negative
+
+- [Drawback 1]
+- [Drawback 2]
+
+### Neutral
+
+- [Side effect]
+
+## Alternatives Considered
+
+### Alternative 1: [Name]
+
+- Pros: [benefits]
+- Cons: [drawbacks]
+- Why rejected: [reason]
+
+### Alternative 2: [Name]
+
+...
+
+## Related Decisions
+
+- [Link to related ADR]
+````
+
+---
+
+## Step 6: Validate Constitution
+
+After creating/updating, validate:
+
+### Consistency Check
+
+- [ ] All principles are actionable (not vague)
+- [ ] No contradictory principles
+- [ ] Examples provided for clarity
+- [ ] Enforcement method defined
+
+### Codebase Alignment Check
+
+```
+Task: subagent_type="codebase-analyzer", model="sonnet"
+Prompt: "Check if the codebase follows these constitution principles:
+[List key principles]
+Report any violations or areas needing attention."
+```
+
+### Completeness Check
+
+- [ ] Coding standards defined
+- [ ] Architecture principles defined
+- [ ] Testing requirements defined
+- [ ] Security guidelines defined
+- [ ] Quality gates defined
+
+---
+
+## Step 7: Report Completion
+
+```
+================================================================
+  CONSTITUTION [CREATED/UPDATED]: [Project Name]
+================================================================
+
+  Location: .specify/memory/constitution.md
+
+  Sections:
+  - Core Principles: [N] defined
+  - Coding Standards: [Complete/Partial]
+  - Architecture: [Complete/Partial]
+  - Testing: [Complete/Partial]
+  - Security: [Complete/Partial]
+  - Quality Gates: [N] checks
+
+  Validation:
+  - Consistency: [Pass/Issues found]
+  - Codebase alignment: [X]% following principles
+  - Completeness: [X]/[Total] sections
+
+  Next Steps:
+  1. Review with team
+  2. Address any violations found
+  3. Add to onboarding documentation
+  4. Reference in /3_gofer_plan for alignment checks
+
+================================================================
+```
+
+---
+
+## Integration with Pipeline
+
+### During Planning (/3_gofer_plan)
+
+```markdown
+## Constitution Check
+
+- [x] P1: [Principle] - Plan aligns
+- [x] P2: [Principle] - Plan aligns
+- [ ] P3: [Principle] - Exception needed (see ADR-NNN)
+```
+
+### During Implementation (/5_gofer_implement)
+
+Before each task, verify implementation follows constitution.
+
+### During Validation (/6_gofer_validate)
+
+```markdown
+## Constitution Compliance
+
+| Principle | Status    | Notes             |
+| --------- | --------- | ----------------- |
+| P1        | Pass      | -                 |
+| P2        | Pass      | -                 |
+| P3        | Exception | ADR-NNN documents |
+```
+
+---
+
+## Updating Constitution
+
+When learnings emerge from feature work:
+
+1. Run `/gofer_constitution` with update flag
+2. Add new principles or modify existing
+3. Create ADR for significant changes
+4. Update version history
+5. Notify team of changes
+
+---
+
+## Observability Logging
+
+```bash
+.specify/scripts/bash/log-stage.sh gofer_constitution --complete --tokens [N] --compactions [N]
+```
+
+---
+
+## Key Rules
+
+- Constitution is **authoritative** - all work must align
+- Principles must be **actionable** - not vague aspirations
+- **Exceptions require ADRs** - no silent violations
+- **Version control** constitution changes
+- Constitution informs **all pipeline stages**