@tgoodington/intuition 11.0.1 → 11.2.0

package/skills/intuition-enuncia-initialize/SKILL.md

@@ -0,0 +1,251 @@
+---
+name: intuition-enuncia-initialize
+description: Set up project memory infrastructure for the Enuncia pipeline with workflow state tracking, memory files, project map, and configuration templates.
+model: haiku
+tools: Read, Write, Glob, Grep, Bash, AskUserQuestion
+allowed-tools: Read, Write, Glob, Grep, Bash
+---
+
+# Initialize - Enuncia Pipeline Setup Protocol
+
+You create the `docs/project_notes/` directory structure, initialize memory files from templates, create the Enuncia workflow state file, set up the project map scaffold, and create project configuration files. You run once per project to set up infrastructure, then hand off to the workflow skills.
+
+## CRITICAL RULES
+
+1. You MUST check install location before doing anything else — enforce global install.
+2. You MUST check if `docs/project_notes/` already exists before creating anything.
+3. You MUST use template files from `references/` directory. Read each template with the Read tool, then Write to the target path.
+4. You MUST create `.project-memory-state.json` using the Enuncia schema from `references/state_template.json`.
+5. You MUST auto-create all configuration files (CLAUDE.md, INTUITION.md, settings, profile) if they do not exist. Do NOT ask — just create them.
+6. You MUST NOT overwrite existing files. If a file already exists, skip it silently.
+7. You MUST NOT invoke other skills. You only set up infrastructure.
+8. You MUST report what was created at the end.
+
+## PROTOCOL: COMPLETE FLOW
+
+```
+Step 0: Check install location — enforce global install
+Step 1: Detect existing setup
+Step 2: Create memory directory and files from templates
+Step 3: Create .project-memory-state.json with Enuncia schema
+Step 4: Update CLAUDE.md with Enuncia workflow protocols
+Step 4.5: Create INTUITION.md framework overview
+Step 5: Create configuration files (settings, user profile)
+Step 6: Report completion and suggest next step
+```
+
+## STEP 0: ENFORCE GLOBAL INSTALL
+
+Before anything else, check whether `@tgoodington/intuition` is installed locally (project-level) vs globally.
+
+Run these checks using Bash:
+
+```
+Local:  npm list @tgoodington/intuition --depth=0 2>&1
+Global: npm list -g @tgoodington/intuition --depth=0 2>&1
+```
+
+Apply this logic:
+
+```
+IF local install found AND global install found:
+  → Uninstall local: npm uninstall @tgoodington/intuition
+  → Notify: "Removed local install. Using global install."
+
+IF local install found AND no global install:
+  → Uninstall local: npm uninstall @tgoodington/intuition
+  → Install global: npm install -g @tgoodington/intuition
+  → Notify: "Moved install from local to global."
+
+IF no local install AND global install found:
+  → Proceed (correct setup)
+
+IF neither found:
+  → Warn: "Package not found. Install with: npm install -g @tgoodington/intuition"
+  → STOP
+```
+
+## STEP 1: DETECT EXISTING SETUP
+
+Check if `docs/project_notes/` exists.
+
+```
+IF docs/project_notes/ exists:
+  → Check which files already exist
+  → Ask user: "Project memory already exists. What would you like to do?"
+    Options:
+    - "Skip existing files, only create missing ones" (Recommended)
+    - "Overwrite everything with fresh templates"
+    - "Cancel — nothing to do"
+
+IF docs/project_notes/ does NOT exist:
+  → Proceed with full setup
+```
+
+Also check if CLAUDE.md exists and whether it already has a "Project Workflow and Memory System" section.
+
+## STEP 2: CREATE MEMORY FILES
+
+Create the directory structure and initialize memory files:
+
+```
+docs/
+└── project_notes/
+    ├── trunk/
+    ├── branches/
+    ├── project_map.md
+    ├── bugs.md
+    ├── decisions.md
+    ├── key_facts.md
+    ├── issues.md
+    └── .project-memory-state.json
+```
+
+Create `docs/project_notes/trunk/` and `docs/project_notes/branches/` as empty directories. Write a `.gitkeep` placeholder to each so they are tracked by git.
+
+For each file, use the Read tool to read the template, then use Write to create the target:
+
+| Template Source | Target File |
+|----------------|-------------|
+| `references/bugs_template.md` | `docs/project_notes/bugs.md` |
+| `references/decisions_template.md` | `docs/project_notes/decisions.md` |
+| `references/key_facts_template.md` | `docs/project_notes/key_facts.md` |
+| `references/issues_template.md` | `docs/project_notes/issues.md` |
+| `references/project_map_template.md` | `docs/project_notes/project_map.md` |
+
+The project map template is a scaffold — compose and design fill it with real content during the workflow.
+
+Do NOT create workflow output files (discovery_brief.md, tasks.json, etc.). Those are created by their respective skills.
+
+## STEP 3: CREATE STATE FILE
+
+Read `references/state_template.json` and write to `docs/project_notes/.project-memory-state.json`.
+
+The state file uses the Enuncia v11 schema:
+
+```json
+{
+  "initialized": true,
+  "version": "11.0",
+  "pipeline": "enuncia",
+  "active_context": "trunk",
+  "trunk": {
+    "status": "none",
+    "workflow": {
+      "discovery": {
+        "started": false,
+        "completed": false,
+        "completed_at": null
+      },
+      "compose": {
+        "started": false,
+        "completed": false,
+        "completed_at": null
+      },
+      "design": {
+        "started": false,
+        "completed": false,
+        "completed_at": null
+      },
+      "execute": {
+        "started": false,
+        "completed": false,
+        "completed_at": null
+      },
+      "verify": {
+        "started": false,
+        "completed": false,
+        "completed_at": null
+      }
+    }
+  },
+  "branches": {},
+  "last_handoff": null,
+  "last_handoff_transition": null
+}
+```
+
+## STEP 4: UPDATE CLAUDE.MD
+
+Read `references/claude_template.md` for the Enuncia workflow protocol content.
+
+```
+IF CLAUDE.md does NOT exist:
+  → Create CLAUDE.md with the template content
+
+IF CLAUDE.md exists BUT has no "Project Workflow and Memory System" section:
+  → Append the template content to the end of the file
+
+IF CLAUDE.md exists AND already has the section:
+  → Skip (do not overwrite)
+```
+
+## STEP 4.5: CREATE INTUITION.MD
+
+Read `references/intuition_readme_template.md` and write to `INTUITION.md` at the project root.
+
+```
+IF INTUITION.md does NOT exist:
+  → Create it from template
+
+IF INTUITION.md already exists:
+  → Skip
+```
+
+## STEP 5: CREATE CONFIGURATION FILES
+
+Auto-create each file if it does not exist. Do NOT ask — just create. If a file already exists, skip it silently.
+
+### 5A: Claude Code Settings
+
+- Read `references/settings_template.json`
+- If `.claude/settings.local.json` does not exist: create from template
+- If `.claude/settings.local.json` exists: skip
+
+### 5B: User Profile
+
+- Read `references/user_profile_template.json`
+- If `.claude/USER_PROFILE.json` does not exist: create from template
+- If `.claude/USER_PROFILE.json` exists: skip
+
+## STEP 6: REPORT COMPLETION
+
+Present a concise summary of what was created vs skipped:
+
+```
+Enuncia pipeline initialized!
+
+Created:
+- [list each file that was created]
+
+Skipped (already existed):
+- [list each file that was skipped, if any]
+
+Next step: Run /intuition-enuncia-discovery to start defining your project,
+or /intuition-enuncia-start to check project status.
+```
+
+## EDGE CASES
+
+- **Partial setup exists**: Check each file individually. Only create missing files.
+- **CLAUDE.md has custom content**: Append the workflow section. Do not replace the entire file.
+- **Git-tracked project**: Memory files in `docs/project_notes/` are safe to commit. Settings in `.claude/` are typically gitignored.
+- **Classic pipeline state exists**: If `.project-memory-state.json` exists with a non-enuncia pipeline, warn the user: "This project has an existing classic pipeline state. Overwriting will reset workflow tracking. Proceed?" Only overwrite if confirmed.
+
+## REFERENCE FILES
+
+These template files are in the `references/` directory. Use Read tool to access them:
+
+**Memory file templates** (Step 2):
+- `bugs_template.md`, `decisions_template.md`, `key_facts_template.md`, `issues_template.md`, `project_map_template.md`
+
+**State template** (Step 3):
+- `state_template.json` — Enuncia v11 workflow state
+
+**Framework overview** (Step 4.5):
+- `intuition_readme_template.md`
+
+**Configuration templates** (Steps 4-5):
+- `claude_template.md` — Enuncia memory protocols for CLAUDE.md
+- `settings_template.json` — pre-authorized tools for Claude Code
+- `user_profile_template.json` — cross-project user context

package/skills/intuition-enuncia-initialize/references/bugs_template.md

@@ -0,0 +1,41 @@
+# Bug Log Template
+
+This file demonstrates the format for logging bugs and their solutions. Keep entries brief and chronological.
+
+## Format
+
+Each bug entry should include:
+- Date (YYYY-MM-DD)
+- Brief description of the bug/issue
+- Solution or fix applied
+- Any prevention notes (optional)
+
+Use bullet lists for simplicity. Older entries can be manually removed when they become irrelevant.
+
+## Example Entries
+
+### 2025-01-15 - Docker Architecture Mismatch
+- **Issue**: Container failing to start with "exec format error"
+- **Root Cause**: Built on ARM64 Mac but deploying to AMD64 Cloud Run
+- **Solution**: Added `--platform linux/amd64` to docker build command
+- **Prevention**: Always specify platform in Dockerfile and build scripts
+
+### 2025-01-20 - Cloud Scheduler HTTPS Requirement
+- **Issue**: Cloud Scheduler jobs failing with "URL must use HTTPS"
+- **Root Cause**: Forgot Cloud Run URLs require HTTPS by default
+- **Solution**: Updated all scheduler job URLs from http:// to https://
+- **Prevention**: Remember GCP services enforce HTTPS; check URLs in infrastructure code
+
+### 2025-01-22 - Database Connection Pool Exhaustion
+- **Issue**: API returning 500 errors under load
+- **Root Cause**: Connection pool size too small (default 5)
+- **Solution**: Increased pool_size to 20 and max_overflow to 10 in SQLAlchemy config
+- **Prevention**: Load test APIs before production deployment
+
+## Tips
+
+- Keep descriptions under 2-3 lines
+- Focus on what was learned, not exhaustive details
+- Include enough context for future reference
+- Date entries so you know how recent the issue is
+- Periodically clean out very old entries (6+ months)

package/skills/intuition-enuncia-initialize/references/claude_template.md

@@ -0,0 +1,33 @@
+## Project Workflow and Memory System
+
+This project uses the Enuncia pipeline (`@tgoodington/intuition`). Run `/intuition-enuncia-start` to check project status and get routed to the next step.
+
+### Memory Files
+
+Project memory is maintained in `docs/project_notes/` for consistency across sessions:
+
+- **bugs.md** — Bug log with dates, solutions, and prevention notes
+- **decisions.md** — Architectural Decision Records (ADRs) with context and trade-offs
+- **key_facts.md** — Project configuration, credentials, ports, important URLs
+- **issues.md** — Work log with ticket IDs, descriptions, and URLs
+- **project_map.md** — Living architecture document, updated as the project evolves
+
+### Memory-Aware Protocols
+
+**Before proposing architectural changes:**
+- Check `docs/project_notes/decisions.md` for existing decisions
+- Verify the proposed approach doesn't conflict with past choices
+- If it does conflict, acknowledge the existing decision and explain why a change is warranted
+
+**When encountering errors or bugs:**
+- Search `docs/project_notes/bugs.md` for similar issues
+- Apply known solutions if found
+- Document new bugs and solutions when resolved
+
+**When looking up project configuration:**
+- Check `docs/project_notes/key_facts.md` for credentials, ports, URLs, service accounts
+- Prefer documented facts over assumptions
+
+**When completing work on tickets:**
+- Log completed work in `docs/project_notes/issues.md`
+- Include ticket ID, date, brief description, and URL

package/skills/intuition-enuncia-initialize/references/decisions_template.md

@@ -0,0 +1,92 @@
+# Architectural Decisions Template
+
+This file demonstrates the format for logging architectural decisions (ADRs). Use bullet lists for clarity.
+
+## Format
+
+Each decision should include:
+- Date and ADR number
+- Context (why the decision was needed)
+- Decision (what was chosen)
+- Alternatives considered
+- Consequences (trade-offs, implications)
+
+## Example Entries
+
+### ADR-001: Use Workload Identity Federation for GitHub Actions (2025-01-10)
+
+**Context:**
+- Need secure authentication from GitHub Actions to GCP
+- Service account keys are deprecated and considered insecure
+- Want to avoid managing long-lived credentials
+
+**Decision:**
+- Use Workload Identity Federation (WIF) for GitHub Actions authentication
+- Configure via `WIF_PROVIDER` and `WIF_SERVICE_ACCOUNT` secrets
+
+**Alternatives Considered:**
+- Service account JSON keys → Rejected: security risk, manual rotation required
+- Environment-specific credentials → Rejected: harder to manage across repos
+
+**Consequences:**
+- ✅ More secure (no long-lived credentials)
+- ✅ Automatic credential rotation
+- ✅ Better audit trail
+- ❌ Slightly more complex initial setup
+- ❌ Requires GitHub OIDC support
+
+### ADR-002: Use Alembic for Database Migrations (2025-01-12)
+
+**Context:**
+- Need version control for database schema changes
+- Multiple developers working on database schema
+- Want to avoid manual SQL scripts and migration conflicts
+
+**Decision:**
+- Use Alembic as the database migration tool
+- Store migrations in `alembic/versions/` directory
+- Use auto-generate feature for model changes
+
+**Alternatives Considered:**
+- Raw SQL scripts → Rejected: no versioning, error-prone
+- Flask-Migrate → Rejected: too tied to Flask framework
+- Django migrations → Rejected: using FastAPI, not Django
+
+**Consequences:**
+- ✅ Version-controlled schema changes
+- ✅ Automatic migration generation from models
+- ✅ Easy rollback capability
+- ❌ Learning curve for team
+- ❌ Must remember to generate migrations after model changes
+
+### ADR-003: Use AlloyDB Instead of Cloud SQL (2025-01-15)
+
+**Context:**
+- Need PostgreSQL-compatible database in GCP
+- Require high availability and automatic backups
+- Performance-critical application with complex queries
+
+**Decision:**
+- Use AlloyDB for PostgreSQL instead of Cloud SQL
+- Configure with automated backups and point-in-time recovery
+
+**Alternatives Considered:**
+- Cloud SQL PostgreSQL → Rejected: slower query performance
+- Self-managed PostgreSQL on GCE → Rejected: high operational overhead
+- Firestore → Rejected: need relational data model and SQL
+
+**Consequences:**
+- ✅ Better query performance (2-4x faster than Cloud SQL)
+- ✅ PostgreSQL compatibility
+- ✅ Managed service (automated backups, HA)
+- ❌ Higher cost than Cloud SQL
+- ❌ Newer service, less community documentation
+
+## Tips
+
+- Number decisions sequentially (ADR-001, ADR-002, etc.)
+- Always include date for context
+- Be honest about trade-offs (use ✅ and ❌)
+- Keep alternatives brief but clear
+- Update decisions if they're revisited/changed
+- Focus on "why" not "how" (implementation details go elsewhere)

package/skills/intuition-enuncia-initialize/references/intuition_readme_template.md

@@ -0,0 +1,50 @@
+# Intuition (Enuncia Pipeline)
+
+A discovery-driven workflow system for Claude Code. Transforms project visions into structured deliverables through foundational discovery, experience-slice decomposition, technical design, and verified implementation.
+
+## Workflow
+
+```
+/intuition-enuncia-discovery → /intuition-enuncia-compose → /intuition-enuncia-design →
+  /intuition-enuncia-execute → /intuition-enuncia-verify → complete
+        ↓
+  /intuition-enuncia-start → create branch or /intuition-debugger
+```
+
+Run `/clear` before each phase skill to keep context clean.
+
+The first cycle is the **trunk**. After trunk completes, create **branches** for new features or changes.
+
+## Skills
+
+| Skill | What it does |
+|-------|-------------|
+| `/intuition-enuncia-start` | Detects where you left off, routes to next step |
+| `/intuition-enuncia-discovery` | Foundational project discovery — Who, Where, What, Why |
+| `/intuition-enuncia-compose` | Maps experience slices, decomposes into buildable tasks |
+| `/intuition-enuncia-design` | Technical design — enriches tasks with specs, updates project map |
+| `/intuition-enuncia-execute` | Delegates production to subagents, verifies outputs |
+| `/intuition-enuncia-verify` | Wires code into project, runs toolchain and tests |
+| `/intuition-enuncia-handoff` | Branch creation and context management |
+| `/intuition-initialize` | Sets up project memory (you already ran this) |
+| `/intuition-meander` | Thought partner — reason through problems collaboratively |
+| `/intuition-think-tank` | Rapid expert-panel analysis |
+| `/intuition-debugger` | Expert diagnostic and resolution service |
+
+## Quick Start
+
+### First cycle (trunk)
+
+1. `/intuition-enuncia-start` — see where you are
+2. `/intuition-enuncia-discovery` — articulate what you're building and why
+3. `/intuition-enuncia-compose` — decompose into experience slices and tasks
+4. `/intuition-enuncia-design` — technical design for each task group
+5. `/intuition-enuncia-execute` — build from specs
+6. `/intuition-enuncia-verify` — wire in, test, prove it works (code projects)
+
+Run `/clear` before each phase skill.
+
+### After trunk completes
+
+- `/intuition-enuncia-start` — see project status, create a branch, or start fresh
+- `/intuition-debugger` — investigate hard problems

package/skills/intuition-enuncia-initialize/references/issues_template.md

@@ -0,0 +1,76 @@
+# Issues/Work Log Template
+
+This file demonstrates the format for logging work completed on tickets. Keep it simple - just enough to remember what was done. Full details live in Jira/GitHub.
+
+## Format
+
+Each entry should include:
+- Date (YYYY-MM-DD)
+- Ticket ID
+- Brief description (1-2 lines)
+- URL to ticket (if available)
+- Status (optional: completed, in-progress, blocked)
+
+Use bullet lists for simplicity. This is NOT a replacement for your ticket system - it's a quick reference log.
+
+## Example Entries
+
+### 2025-01-15 - PROJ-123: Implement Contact API
+- **Status**: Completed
+- **Description**: Created FastAPI endpoints for contact CRUD operations with validation
+- **URL**: https://jira.company.com/browse/PROJ-123
+- **Notes**: Added unit tests, coverage at 85%
+
+### 2025-01-16 - PROJ-124: Fix Docker Build Issues
+- **Status**: Completed
+- **Description**: Fixed architecture mismatch for Cloud Run deployment
+- **URL**: https://jira.company.com/browse/PROJ-124
+- **Notes**: See bugs.md for details on the fix
+
+### 2025-01-18 - PROJ-125: Database Migration to AlloyDB
+- **Status**: Completed
+- **Description**: Migrated from Cloud SQL to AlloyDB with Pulumi infrastructure code
+- **URL**: https://jira.company.com/browse/PROJ-125
+- **Notes**: Multi-phase migration completed over 3 days
+
+### 2025-01-20 - GH-45: Add OAuth2 Authentication
+- **Status**: In Progress
+- **Description**: Implementing OAuth2 flow with Google provider
+- **URL**: https://github.com/company/repo/issues/45
+- **Notes**: Backend complete, frontend integration pending
+
+### 2025-01-22 - PROJ-130: Performance Optimization
+- **Status**: Blocked
+- **Description**: Optimize slow queries in contact search endpoint
+- **URL**: https://jira.company.com/browse/PROJ-130
+- **Notes**: Waiting for DBA review of proposed indexes
+
+## Alternative Format (Grouped by Week)
+
+### Week of 2025-01-15
+
+**Completed:**
+- PROJ-123: Contact API implementation → https://jira.company.com/browse/PROJ-123
+- PROJ-124: Docker build fix → https://jira.company.com/browse/PROJ-124
+
+**In Progress:**
+- PROJ-125: AlloyDB migration (phase 2 of 3)
+
+### Week of 2025-01-22
+
+**Completed:**
+- PROJ-125: AlloyDB migration completed → https://jira.company.com/browse/PROJ-125
+- GH-45: OAuth2 backend done → https://github.com/company/repo/issues/45
+
+**Blocked:**
+- PROJ-130: Query optimization (waiting on DBA) → https://jira.company.com/browse/PROJ-130
+
+## Tips
+
+- Keep descriptions brief (1-2 lines max)
+- Always include ticket URL for easy reference
+- Update status if work gets blocked or resumed
+- Optional: Group by week or sprint for better organization
+- Don't duplicate ticket details - link to source of truth
+- Clean out very old entries periodically (3+ months)
+- Include both Jira and GitHub tickets as appropriate