eai-cli 0.0.0-bootstrap.0

package/resources/gofer/templates/session-handoff-template.md

@@ -0,0 +1,172 @@
+---
+feature: '[Feature Name]'
+session: 1
+previousSession: null
+created: '[ISO timestamp]'
+contextUsage: '[N%]'
+stage: '[current stage]'
+---
+
+# Session Handoff: [Feature Name]
+
+## Session Summary
+
+**Session**: #[N] of [Feature Name] implementation **Date**: [ISO timestamp]
+**Stage at End**: [1_research / 2_specify / 3_plan / 4_tasks / 5_implement /
+6_validate] **Context Usage**: [N%] at session end
+
+---
+
+## Work Completed
+
+### This Session
+
+- [x] [Major accomplishment 1]
+- [x] [Major accomplishment 2]
+- [x] [Major accomplishment 3]
+
+### Cumulative Progress
+
+| Stage       | Status         | Notes                          |
+| ----------- | -------------- | ------------------------------ |
+| 1_research  | ✓ Complete     | research.md created            |
+| 2_specify   | ✓ Complete     | spec.md created                |
+| 3_plan      | ✓ Complete     | plan.md, data-model.md created |
+| 4_tasks     | ✓ Complete     | tasks.md with N tasks          |
+| 5_implement | ⏳ In Progress | N/M tasks complete             |
+| 6_validate  | ○ Not Started  | -                              |
+
+---
+
+## Current State
+
+### Files Modified This Session
+
+| File               | Change Type | Description    |
+| ------------------ | ----------- | -------------- |
+| `path/to/file1.ts` | Created     | [What it does] |
+| `path/to/file2.ts` | Modified    | [What changed] |
+
+### Git State
+
+```
+Branch: [branch-name]
+Last Commit: [commit hash] - [commit message]
+Uncommitted Changes: [yes/no - list if yes]
+```
+
+### Build/Test Status
+
+- **Build**: [✓ Passing / ✗ Failing - reason]
+- **Tests**: [✓ N/N passing / ✗ N failures - list]
+- **Lint**: [✓ Clean / ⚠️ N warnings / ✗ N errors]
+- **Types**: [✓ Valid / ✗ N errors]
+
+---
+
+## Next Steps
+
+### Immediate (Next Session)
+
+1. [ ] [First thing to do when resuming]
+2. [ ] [Second thing to do]
+3. [ ] [Third thing to do]
+
+### Remaining Work
+
+From tasks.md, the following remains:
+
+- [ ] [Task ID]: [Description]
+- [ ] [Task ID]: [Description]
+- [ ] [Task ID]: [Description]
+
+**Estimated Remaining**: [N] tasks across [N] phases
+
+---
+
+## Key Decisions Made
+
+Decisions that MUST be preserved for context continuity:
+
+### Decision 1: [Topic]
+
+- **What**: [The decision made]
+- **Why**: [Rationale]
+- **Impact**: [How this affects implementation]
+
+### Decision 2: [Topic]
+
+- **What**: [The decision made]
+- **Why**: [Rationale]
+- **Impact**: [How this affects implementation]
+
+---
+
+## Context to Preserve
+
+### Critical Information
+
+The following context is essential and must be loaded in the next session:
+
+1. **[Topic 1]**: [Brief explanation of why this matters]
+2. **[Topic 2]**: [Brief explanation]
+3. **[Topic 3]**: [Brief explanation]
+
+### Files to Review First
+
+When resuming, start by reading:
+
+1. `{FEATURE_DIR}/tasks.md` - Current task status
+2. `{FEATURE_DIR}/plan.md` - Architecture reference
+3. [Other critical file]
+
+---
+
+## Known Issues / Blockers
+
+### Active Issues
+
+| Issue     | Severity       | Status               | Notes     |
+| --------- | -------------- | -------------------- | --------- |
+| [Issue 1] | [High/Med/Low] | [Open/Investigating] | [Details] |
+
+### Resolved This Session
+
+- [Issue that was resolved]: [How it was fixed]
+
+---
+
+## Session Metrics
+
+| Metric              | Value |
+| ------------------- | ----- |
+| Tasks Completed     | N     |
+| Files Created       | N     |
+| Files Modified      | N     |
+| Tests Added         | N     |
+| Context Compactions | N     |
+| Errors Encountered  | N     |
+
+---
+
+## Resume Instructions
+
+To continue this work in a new session:
+
+1. Read this handoff document first
+2. Run `check-context-health.sh` to verify context capacity
+3. Load tasks.md to see current progress
+4. Start from "Immediate (Next Session)" tasks above
+5. Mark this handoff as "superseded" once work resumes
+
+---
+
+## Handoff Verification
+
+Before ending this session, verify:
+
+- [ ] All work is committed or documented
+- [ ] Build passes
+- [ ] No uncommitted changes that would be lost
+- [ ] Next steps are clear and actionable
+- [ ] Key decisions are documented above

package/resources/gofer/templates/spec-summary-template.md

@@ -0,0 +1,118 @@
+---
+feature: '{{feature-name}}'
+created: '{{ISO-timestamp}}'
+audience: business-stakeholders
+spec-reference: spec.md
+---
+
+# {{feature-name}} — Executive Summary
+
+## What We're Building
+
+{{3-sentence-plain-english-summary-of-the-feature}}
+
+## Why It Matters
+
+**Problem**: {{from-problem-brief-root-cause}} **Impact**:
+{{from-problem-brief-annual-impact}} **Solution**:
+{{one-sentence-how-this-fixes-it}}
+
+## What Changes for Users
+
+| Who             | Before (Today)   | After (With This Feature) |
+| --------------- | ---------------- | ------------------------- |
+| {{user-role-1}} | {{current-pain}} | {{improved-experience}}   |
+| {{user-role-2}} | {{current-pain}} | {{improved-experience}}   |
+
+## AI-Augmented Process
+
+For app delivery, Gofer defaults to a four-step-or-fewer journey where
+generative AI helps the user complete each business goal. For non-app work,
+explain why this section is not applicable.
+
+| Step | Business Goal | Generative AI Help | User Control |
+| ---- | ------------- | ------------------ | ------------ |
+| 1    | {{goal}}      | {{assist}}         | {{control}}  |
+| 2    | {{goal}}      | {{assist}}         | {{control}}  |
+| 3    | {{goal}}      | {{assist}}         | {{control}}  |
+| 4    | {{goal}}      | {{assist}}         | {{control}}  |
+
+## Implementation Approach
+
+**Selected Option**: Option {{N}} — {{name}} **Complexity**: {{Low/Medium/High}}
+**Estimated Effort**: {{timeframe}}
+
+### What's Included
+
+- {{capability-1-in-plain-english}}
+- {{capability-2-in-plain-english}}
+- {{capability-3-in-plain-english}}
+
+### What's NOT Included
+
+- {{exclusion-1}} — {{why-excluded-or-planned-for-later}}
+- {{exclusion-2}} — {{why-excluded-or-planned-for-later}}
+
+## Risk Assessment
+
+| Risk                | Likelihood | Impact     | Mitigation           |
+| ------------------- | ---------- | ---------- | -------------------- |
+| {{business-risk-1}} | Low/Med/Hi | Low/Med/Hi | {{how-we-handle-it}} |
+| {{business-risk-2}} | Low/Med/Hi | Low/Med/Hi | {{how-we-handle-it}} |
+
+## ROI Estimate
+
+| Metric                    | Value         |
+| ------------------------- | ------------- |
+| Development cost estimate | {{estimate}}  |
+| Annual value delivered    | {{estimate}}  |
+| Payback period            | {{timeframe}} |
+| Break-even point          | {{date}}      |
+
+## Key Assumptions
+
+These assumptions underpin the business case. If any prove false, the plan may
+need adjustment:
+
+1. {{critical-assumption-1}} — {{status: VALIDATED/UNVALIDATED}}
+2. {{critical-assumption-2}} — {{status: VALIDATED/UNVALIDATED}}
+
+## Decision Points
+
+Before implementation proceeds, the following decisions are needed:
+
+- [ ] **Approve scope**: Is the included/excluded list correct?
+- [ ] **Confirm budget**: Is the estimated effort acceptable?
+- [ ] **Accept risks**: Are the identified risks manageable?
+- [ ] **Validate assumptions**: Are the key assumptions reasonable?
+
+## Enterprise Decision Rights
+
+Standard Gofer delivery is the public default. For explicit EnterpriseAI profile
+runs, the summary must identify the decision-rights audiences and the
+information each needs before the feature can move forward.
+
+| Persona                 | Decision They Own                                | Evidence Required                            |
+| ----------------------- | ------------------------------------------------ | -------------------------------------------- |
+| Executive committee     | Strategic value, sponsorship, funding gate       | Executive summary, ROI, risk appetite        |
+| Business owner          | User journey, adoption, success metrics          | Problem brief, journey, value targets        |
+| Internal delivery       | Delivery plan, dependencies, red/green readiness | Tasks, validation plan, audit history        |
+| Enterprise architecture | Platform fit, reuse, contract boundaries         | Context bundle, contract pack, reuse scan    |
+| CISO                    | Identity, tenant boundary, residual risk         | Controls, validation report, exceptions      |
+| Data architecture       | Object model, lineage, quality controls          | Data model, lineage, quality tests           |
+| CIO                     | Platform strategy and operating model            | Roadmap fit, run model, support ownership    |
+| CFO                     | Investment case and benefit tracking             | Cost estimate, benefit baseline, value owner |
+| COO                     | Operational readiness and rollout                | Change plan, support model, 30-day metrics   |
+| Risk/compliance         | Obligations, evidence, exceptions                | Audit history, policy mapping, expiry dates  |
+
+## How We'll Measure Success
+
+| Success Metric | Target     | When We'll Know |
+| -------------- | ---------- | --------------- |
+| {{metric-1}}   | {{target}} | {{timeframe}}   |
+| {{metric-2}}   | {{target}} | {{timeframe}}   |
+
+---
+
+_This is a business summary. For full technical specification, see `spec.md`._
+_For implementation details, see `plan.md`._

package/resources/gofer/templates/spec-template.md

@@ -0,0 +1,196 @@
+# Feature Specification: [FEATURE NAME]
+
+**Feature Branch**: `[###-feature-name]` **Created**: [DATE] **Status**: Draft
+**Input**: User description: "$ARGUMENTS"
+
+<!--
+  This template is filled in by /2_gofer_specify (or legacy /2_gofer_specify).
+  Recommended: Use /0_gofer_start to auto-chain the entire pipeline.
+  Location: .specify/specs/[###-feature-name]/spec.md
+-->
+
+## Executive Summary
+
+[Three to five plain-language bullets covering the user problem, target outcome,
+highest-priority journey, success measure, and any decision still needed.]
+
+## Branding And Presentation Requirements
+
+For app delivery or stakeholder-heavy work, state whether company, client,
+consulting-firm, co-branded, or neutral presentation is required. Link to
+`.specify/memory/brand-profile.json` when available and identify any pending
+brand approvals, logo constraints, confidentiality labels, or deck requirements.
+If branding is not in scope, state `N/A`.
+
+## Goal Ledger Alignment
+
+Keep `.specify/specs/[###-feature-name]/goal-ledger.json` aligned with this
+specification so downstream stages can detect objective drift and reopen the
+right mini-loop automatically.
+
+| Goal ID | Outcome   | Metric / Target   | Linked Stories | Linked Requirements |
+| ------- | --------- | ----------------- | -------------- | ------------------- |
+| G1      | [Outcome] | [Metric / target] | [US1]          | [FR-001, SC-001]    |
+
+## User Scenarios & Testing _(mandatory)_
+
+<!--
+  IMPORTANT: User stories should be PRIORITIZED as user journeys ordered by importance.
+  Each user story/journey must be INDEPENDENTLY TESTABLE - meaning if you implement just ONE of them,
+  you should still have a viable MVP (Minimum Viable Product) that delivers value.
+
+  Assign priorities (P1, P2, P3, etc.) to each story, where P1 is the most critical.
+  Think of each story as a standalone slice of functionality that can be:
+  - Developed independently
+  - Tested independently
+  - Deployed independently
+  - Demonstrated to users independently
+-->
+
+### User Story 1 - [Brief Title] (Priority: P1)
+
+[Describe this user journey in plain language]
+
+**Why this priority**: [Explain the value and why it has this priority level]
+
+**Independent Test**: [Describe how this can be tested independently - e.g.,
+"Can be fully tested by [specific action] and delivers [specific value]"]
+
+**Acceptance Scenarios**:
+
+1. **Given** [initial state], **When** [action], **Then** [expected outcome]
+2. **Given** [initial state], **When** [action], **Then** [expected outcome]
+
+---
+
+### User Story 2 - [Brief Title] (Priority: P2)
+
+[Describe this user journey in plain language]
+
+**Why this priority**: [Explain the value and why it has this priority level]
+
+**Independent Test**: [Describe how this can be tested independently]
+
+**Acceptance Scenarios**:
+
+1. **Given** [initial state], **When** [action], **Then** [expected outcome]
+
+---
+
+### User Story 3 - [Brief Title] (Priority: P3)
+
+[Describe this user journey in plain language]
+
+**Why this priority**: [Explain the value and why it has this priority level]
+
+**Independent Test**: [Describe how this can be tested independently]
+
+**Acceptance Scenarios**:
+
+1. **Given** [initial state], **When** [action], **Then** [expected outcome]
+
+---
+
+[Add more user stories as needed, each with an assigned priority]
+
+### Edge Cases
+
+<!--
+  ACTION REQUIRED: The content in this section represents placeholders.
+  Fill them out with the right edge cases.
+-->
+
+- What happens when [boundary condition]?
+- How does system handle [error scenario]?
+
+## Requirements _(mandatory)_
+
+<!--
+  ACTION REQUIRED: The content in this section represents placeholders.
+  Fill them out with the right functional requirements.
+-->
+
+### Functional Requirements
+
+- **FR-001**: System MUST [specific capability, e.g., "allow users to create
+  accounts"]
+- **FR-002**: System MUST [specific capability, e.g., "validate email
+  addresses"]
+- **FR-003**: Users MUST be able to [key interaction, e.g., "reset their
+  password"]
+- **FR-004**: System MUST [data requirement, e.g., "persist user preferences"]
+- **FR-005**: System MUST [behavior, e.g., "log all security events"]
+
+_Example of marking unclear requirements:_
+
+- **FR-006**: System MUST authenticate users via [NEEDS CLARIFICATION: auth
+  method not specified - email/password, SSO, OAuth?]
+- **FR-007**: System MUST retain user data for [NEEDS CLARIFICATION: retention
+  period not specified]
+
+### Key Entities _(include if feature involves data)_
+
+- **[Entity 1]**: [What it represents, key attributes without implementation]
+- **[Entity 2]**: [What it represents, relationships to other entities]
+
+## Application Classification & Journey
+
+- **Mode**: [application delivery | non-app work]
+- **Shared numbered stages preserved**: yes
+- **Journey requirement**: [four-step AI-augmented journey | not applicable]
+- **App stack policy**: [EAI Platform including app template first, Azure second
+  | approved non-EAI exception | not applicable]
+
+## UI Preview & Approval Gate _(application delivery only)_
+
+- **First MVP preview**: [what must be shown first]
+- **Profile choice**: [external / internal / hybrid]
+- **Package lane**: [public-package / internal-app / hybrid-adapter / app-local]
+- **Coupling status**: [source-platform-coupled / source-platform-decoupled /
+  hybrid-adapter]
+- **Public-readiness target**: [required / deferred / not applicable]
+- **EAI App Template constraints**: [which approved blocks/patterns must be
+  reused]
+- **Block catalog evidence**: [`eai blocks list`, `eai blocks describe <id>`,
+  selected block IDs, and any custom-block exception]
+- **Resource bindings**: [`eai resources schema` fields/actions/events used by
+  selected blocks]
+- **Storybook story IDs**: [story IDs for reusable/ported blocks, or approved
+  exception]
+- **Theme override points**: [tokens, slots, CSS variables, data/action hooks]
+- **Block porting and source-platform decoupling**: [reuse/port/custom decision
+  and adapter/resource-schema boundary]
+- **Branding scope**: [logos/styling in scope or not]
+- **Preview validation requirement**: [screenshot, local render proof,
+  Playwright-style checks]
+- **Approval requirement**: [who approves and what artifact records it]
+
+## EnterpriseAI Service Fit _(application delivery only)_
+
+- **Capability selection must happen**: after UI approval and before plan/tasks
+  are considered complete
+- **Evidence sources**: [`eai --describe`, `eai whoami`, `eai tenant select`,
+  `eai resources schema`, `eai verify calls --format json`, or approved
+  equivalent]
+- **Decision states**: [accessible now | purchasable but unavailable now |
+  unavailable without new platform work]
+- **Non-EAI stack handling**: [not used | integration target | migration
+  reference | approved exception with owner/expiry]
+
+## Success Criteria _(mandatory)_
+
+<!--
+  ACTION REQUIRED: Define measurable success criteria.
+  These must be technology-agnostic and measurable.
+-->
+
+### Measurable Outcomes
+
+- **SC-001**: [Measurable metric, e.g., "Users can complete account creation in
+  under 2 minutes"]
+- **SC-002**: [Measurable metric, e.g., "System handles 1000 concurrent users
+  without degradation"]
+- **SC-003**: [User satisfaction metric, e.g., "90% of users successfully
+  complete primary task on first attempt"]
+- **SC-004**: [Business metric, e.g., "Reduce support tickets related to [X] by
+  50%"]