class-ai-agent 1.2.2 → 1.3.0

package/.kiro/commands/debug.md

@@ -0,0 +1,243 @@
+---
+name: debug
+description: Systematic debugging and error recovery — find root cause, not symptoms
+---
+
+# /debug — Debugging & Error Recovery
+
+> "Fix root causes, not symptoms."
+
+## Purpose
+
+Systematically diagnose and fix errors. Stop feature work, preserve evidence, find root cause, add guards, then resume.
+
+## The Stop-the-Line Rule
+
+When unexpected failures occur:
+
+1. **STOP** — Halt feature work immediately
+2. **PRESERVE** — Save error messages, logs, stack traces
+3. **DIAGNOSE** — Follow the 6-step triage process
+4. **FIX** — Address root cause, not symptoms
+5. **GUARD** — Add tests to prevent recurrence
+6. **RESUME** — Only continue after verification; update `.agent/SESSION.md` with root cause, guard tests, and **Next**
+
+---
+
+## 6-Step Triage Process
+
+### Step 1: Reproduce
+
+Make the failure happen reliably.
+
+```bash
+# Run the failing test
+npm test -- --grep "failing test name"
+
+# Or reproduce manually with specific steps
+```
+
+**If not reproducible**, investigate:
+- Timing/race conditions
+- Environment differences (dev vs CI)
+- State leakage between tests
+- Random/flaky behavior
+
+### Step 2: Localize
+
+Identify which layer fails:
+
+| Layer | Symptoms |
+|-------|----------|
+| **UI/Frontend** | Render errors, missing elements, wrong display |
+| **API/Backend** | HTTP errors, wrong responses, timeout |
+| **Database** | Query errors, constraint violations, missing data |
+| **Build** | Compilation errors, missing dependencies |
+| **External** | Third-party API failures, network issues |
+| **Test itself** | Flaky assertion, wrong expectations |
+
+**Use `git bisect` for regressions:**
+
+```bash
+git bisect start
+git bisect bad HEAD
+git bisect good <last-known-good-commit>
+# Git will guide you to the breaking commit
+```
+
+### Step 3: Reduce
+
+Strip away unrelated elements:
+
+```javascript
+// Original complex failing code
+const result = await complexFunction(
+  await getConfig(),
+  await fetchData(),
+  processOptions(opts)
+);
+
+// Reduced to find the problem
+const config = await getConfig();
+console.log('config:', config);  // Check each step
+
+const data = await fetchData();
+console.log('data:', data);
+
+const result = await complexFunction(config, data, opts);
+```
+
+### Step 4: Fix Root Cause
+
+**Fix the actual problem, not the symptom:**
+
+| Symptom | Bad Fix | Good Fix |
+|---------|---------|----------|
+| Duplicate list items | Dedupe in UI | Fix query returning duplicates |
+| Null reference error | Add `?.` everywhere | Ensure data is loaded before access |
+| Slow API response | Increase timeout | Optimize the query |
+| Flaky test | Add retry logic | Fix the race condition |
+
+### Step 5: Guard Against Recurrence
+
+Write a test that catches this specific failure:
+
+```javascript
+it('should not return duplicate items (regression #123)', async () => {
+  // Setup that caused the original bug
+  await createOrder({ items: [item, item] });
+  
+  // The query that was returning duplicates
+  const result = await getOrderItems();
+  
+  // Guard: ensure no duplicates
+  const ids = result.map(r => r.id);
+  expect(ids).toEqual([...new Set(ids)]);
+});
+```
+
+### Step 6: Verify End-to-End
+
+```bash
+# Run the specific test
+npm test -- --grep "regression"
+
+# Run full test suite
+npm test
+
+# Run build
+npm run build
+
+# Manual verification if needed
+```
+
+---
+
+## Error-Specific Triage Trees
+
+### Test Failure
+
+```
+Test fails
+├── Assertion error
+│   ├── Expected value wrong → Check test expectation
+│   └── Actual value wrong → Debug implementation
+├── Runtime error
+│   ├── ReferenceError → Check imports, variable names
+│   ├── TypeError → Check types, null checks
+│   └── NetworkError → Check test setup, mocks
+└── Timeout
+    ├── Async not awaited → Add missing await
+    └── Infinite loop → Check loop conditions
+```
+
+### Build Error
+
+```
+Build fails
+├── TypeScript error
+│   ├── Type mismatch → Fix types or add assertion
+│   └── Missing import → Add import statement
+├── Module not found
+│   ├── Package missing → npm install
+│   └── Path wrong → Fix import path
+└── Syntax error
+    └── Check recent changes → git diff
+```
+
+### Runtime Error
+
+```
+Runtime error
+├── API returns error
+│   ├── 4xx → Client issue, check request
+│   └── 5xx → Server issue, check logs
+├── CORS error
+│   └── Check server CORS config
+├── Undefined/null
+│   └── Add loading state or null check
+└── Network timeout
+    └── Check connectivity, increase timeout
+```
+
+---
+
+## Debugging Tools
+
+### Console Logging (Temporary)
+
+```javascript
+// Add strategic logs
+console.log('[DEBUG] Input:', input);
+console.log('[DEBUG] After transform:', result);
+
+// Remove all debug logs before commit
+git diff | grep console.log
+```
+
+### Node Inspector
+
+```bash
+# Debug Node.js
+node --inspect-brk src/index.js
+
+# Debug tests
+node --inspect-brk node_modules/.bin/vitest
+```
+
+### Git Bisect
+
+```bash
+git bisect start
+git bisect bad                    # Current commit is broken
+git bisect good abc123            # This commit was working
+# Test each commit git suggests
+git bisect good  # or  git bisect bad
+git bisect reset                  # When done
+```
+
+---
+
+## Common Rationalizations (Avoid These)
+
+| Excuse | Reality |
+|--------|---------|
+| "It works on my machine" | Environment differences are bugs |
+| "It's just flaky" | Flaky tests have root causes |
+| "Let's just retry" | Retries hide real problems |
+| "It's a third-party issue" | Still need to handle gracefully |
+| "We'll fix it later" | Tech debt compounds |
+
+---
+
+## Output
+
+- Root cause identified and fixed
+- Regression test added
+- All tests passing
+- Clear commit message explaining the fix
+- **`.agent/SESSION.md`** updated (Gotchas, Decisions, **Next**)
+
+## Next Step
+
+After fixing, continue with `/build` or run `/review` for verification.

package/.kiro/commands/deploy.md

@@ -0,0 +1,40 @@
+# Deploy Command
+
+## Description
+Deploy the application to the target environment.
+
+## Usage
+Tell Claude: "Run the deploy command" or "Deploy to [environment]"
+
+## Steps
+
+### 1. Pre-deploy Checklist
+- [ ] All tests pass (`npm test`)
+- [ ] No linting errors (`npm run lint`)
+- [ ] Environment variables are configured
+- [ ] Database migrations are ready
+
+### 2. Build
+```bash
+npm run build
+```
+
+### 3. Deploy
+```bash
+# Development
+npm run deploy:dev
+
+# Production
+npm run deploy:prod
+```
+
+### 4. Post-deploy Verification
+- Check application health endpoint
+- Verify logs for errors
+- Run smoke tests
+
+## Rollback
+If deployment fails:
+```bash
+npm run rollback
+```

package/.kiro/commands/fix-issue.md

@@ -0,0 +1,42 @@
+# Fix Issue Command
+
+## Description
+Analyze and fix a reported bug or issue systematically.
+
+## Usage
+Tell Claude: "Fix issue: [describe the issue]" or "Fix bug in [file/module]"
+
+## Process
+
+### 1. Understand the Issue
+- Read the error message or bug description carefully
+- Identify the affected component(s)
+- Reproduce the issue locally if possible
+
+### 2. Root Cause Analysis
+- Check recent git changes: `git log --oneline -20`
+- Review affected files
+- Look for related tests that may reveal expected behavior
+
+### 3. Plan the Fix
+- Identify the minimal change needed
+- Consider side effects on other components
+- Update or add tests to cover the fix
+
+### 4. Implement
+- Make the targeted fix
+- Ensure code follows `.claude/rules/code-style.md`
+- Handle errors per `.claude/rules/error-handling.md`
+
+### 5. Verify
+- Run relevant tests: `npm test -- --testPathPattern=[affected]`
+- Run full test suite: `npm test`
+- Check linting: `npm run lint`
+
+### 6. Commit
+Follow `.claude/rules/git-workflow.md`:
+```
+fix: [short description of the fix]
+
+Closes #[issue-number]
+```

package/.kiro/commands/handoff.md

@@ -0,0 +1,94 @@
+---
+name: handoff
+description: End-of-session — update .agent/SESSION.md for the next agent or tool
+---
+
+# /handoff — Session handoff
+
+> "Leave the next agent a map, not a maze."
+
+## Purpose
+
+Capture current work in **`.agent/SESSION.md`** so another chat, persona, or tool (Cursor, Claude Code, Kiro) can continue without re-discovering context.
+
+## When to use
+
+- End of a work session (before closing chat)
+- Switching tools (Cursor → Claude Code → Kiro)
+- Switching persona (e.g. architect → backend)
+- After completing a workflow phase (spec, plan, build, test, review)
+- Before opening a PR (document what reviewers should know)
+
+## Prerequisites
+
+- `.agent/SESSION.md` exists (created by `npx class-ai-agent` or copy from `.agent/SESSION.template.md`)
+- You have context on what was done this session
+
+## Workflow
+
+### Phase 1: Gather state
+
+1. **Review git** — branch name, uncommitted files, last commits
+2. **Review tasks** — open `tasks/todo.md`; sync checkboxes with reality
+3. **Review spec** — note linked `SPEC.md` or `docs/specs/...` path
+4. **Scan decisions** — what did we choose that is not obvious from code alone?
+5. **Scan gotchas** — what failed, env quirks, commands that matter
+
+### Phase 2: Update `.agent/SESSION.md`
+
+Refresh every section (use `.agent/SESSION.template.md` as schema):
+
+| Section | Content |
+|---------|---------|
+| **Meta** | `Updated` (today), `Phase`, `Tool` (cursor/claude/kiro), optional `Persona` |
+| **Goal** | One paragraph — still accurate? |
+| **Done** | Bullets with file paths or commit refs |
+| **In progress** | Current task; **Blockers** (none or describe) |
+| **Next** | Numbered steps for the *next* agent |
+| **Decisions** | Non-obvious choices made this session |
+| **Gotchas** | Failed attempts, test commands, env notes |
+| **Pointers** | Spec path, `tasks/todo.md`, branch, key files |
+
+### Phase 3: Sync `tasks/todo.md`
+
+- Mark completed items `[x]`
+- Add new tasks discovered during work
+- Remove or defer items that are out of scope
+
+### Phase 4: Risk note (if applicable)
+
+If work is **not** safe to pick up blindly, add under **Gotchas** or **In progress**:
+
+- Uncommitted changes and why
+- Failing tests or broken build
+- External blockers (API, review, dependency)
+
+### Phase 5: Optional milestone archive
+
+For major milestones, copy `SESSION.md` to:
+
+```
+.agent/history/YYYY-MM-DD-short-slug.md
+```
+
+Commit both `SESSION.md` and the history file when ready.
+
+## Security
+
+**Never** write to `SESSION.md`:
+
+- API keys, passwords, tokens, credentials
+- PII or customer data
+- Full stack traces with secrets
+
+Use issue links or commit SHAs instead.
+
+## Output
+
+- Updated **`.agent/SESSION.md`**
+- Updated **`tasks/todo.md`** (if it exists)
+- Short summary for the user: phase, next steps, blockers
+
+## Next step
+
+Tell the user to run **`/resume`** in the next session or tool, or commit and share the branch.

package/.kiro/commands/plan.md

@@ -0,0 +1,126 @@
+---
+name: plan
+description: Decompose specs into small, verifiable tasks with dependency ordering
+---
+
+# /plan — Planning & Task Breakdown
+
+> "Vertical slices, not horizontal layers."
+
+## Purpose
+
+Transform a specification into an ordered list of small, verifiable tasks. Each task delivers end-to-end functionality.
+
+## Prerequisites
+
+- A specification exists (`SPEC.md` or described requirements)
+- Understanding of the codebase structure
+
+## Workflow
+
+### Phase 1: Analysis (Read-Only)
+
+1. **Read the spec** — Understand objectives and acceptance criteria
+2. **Survey the codebase** — Identify relevant files, patterns, and integration points
+3. **Map dependencies** — Which components depend on which?
+
+> **Do NOT modify code during planning.**
+
+### Phase 2: Vertical Slicing
+
+Break work into **vertical slices** — each slice delivers complete functionality through all layers:
+
+```
+❌ Horizontal (anti-pattern):
+   Task 1: Create all DB models
+   Task 2: Create all API routes
+   Task 3: Create all UI components
+
+✅ Vertical (correct):
+   Task 1: User can create a task (DB + API + UI)
+   Task 2: User can view task list (DB + API + UI)
+   Task 3: User can mark task complete (DB + API + UI)
+```
+
+### Phase 3: Task Definition
+
+Each task must include:
+
+```markdown
+## Task: [Short description]
+
+**Objective**: [What this achieves]
+
+**Files to modify**:
+- `src/models/task.ts`
+- `src/routes/tasks.ts`
+- `src/components/TaskList.tsx`
+
+**Acceptance Criteria**:
+- [ ] User can [action]
+- [ ] [Validation] is enforced
+- [ ] Test covers [scenario]
+
+**Dependencies**: [Task IDs this depends on]
+
+**Verification**:
+- [ ] Unit tests pass
+- [ ] Integration test added
+- [ ] Manual verification: [steps]
+```
+
+### Phase 4: Ordering
+
+Order tasks by:
+1. **Foundation first** — DB models, types, shared utilities
+2. **Risk-first** — Tackle uncertain/complex items early
+3. **Dependencies** — Respect the dependency graph
+4. **Quick wins** — Early momentum with smaller tasks
+
+### Phase 5: Checkpoints
+
+Insert checkpoints between major phases:
+
+```markdown
+---
+## Checkpoint: Core CRUD Complete
+
+**Verify before proceeding**:
+- [ ] All CRUD operations work
+- [ ] Test coverage > 80%
+- [ ] No console errors
+- [ ] Performance acceptable
+
+---
+```
+
+## Output
+
+Save to `tasks/` directory:
+
+- `tasks/plan.md` — Full planning document with context
+- `tasks/todo.md` — Actionable task checklist
+- **`.agent/SESSION.md`** — Update Meta `phase` to `build`, **Pointers** → `tasks/todo.md` and spec path, **Next** → first `/build` task
+
+```markdown
+# TODO: [Feature Name]
+
+## Phase 1: Foundation
+- [ ] Task 1.1: [Description]
+- [ ] Task 1.2: [Description]
+
+## Checkpoint: Foundation Complete
+
+## Phase 2: Core Features
+- [ ] Task 2.1: [Description]
+- [ ] Task 2.2: [Description]
+
+## Checkpoint: Core Complete
+
+## Phase 3: Polish
+- [ ] Task 3.1: [Description]
+```
+
+## Next Step
+
+After plan is approved, run `/build` to implement tasks incrementally.

package/.kiro/commands/publish-npm.md

@@ -0,0 +1,119 @@
+# Publish to npm (maintainers)
+
+## Description
+
+Publish **`class-ai-agent`** to the npm registry: draft release notes from git, get maintainer approval, update README, bump version, verify CLI, publish.
+
+## Triggers
+
+Use when the maintainer says any of:
+
+- **push to npm repo**
+- **publish to npm**
+- **publish class-ai-agent**
+
+Or **@ mention this file** in Chat/Composer (`.cursor/commands/publish-npm.md` in Cursor; `.kiro/commands/publish-npm.md` in Kiro).
+
+## Prerequisites
+
+- Changes are ready to ship; working tree reflects what you are publishing.
+- **`npm login`** completed for the `class-ai-agent` package scope.
+- Two-factor auth enabled for npm **writes** if the account requires it (see README *Publishing to npm*).
+
+## Workflow
+
+### 1. Resolve baseline version
+
+```bash
+git tag -l 'v*' --sort=-v:refname | head -1
+```
+
+If no `v*` tags exist, use the latest `### x.y.z` heading under **## Release notes** in README, or `package.json` version as the last shipped baseline.
+
+Strip a leading `v` from tags when comparing to semver (e.g. `v1.2.4` → `1.2.4`).
+
+### 2. Draft release notes (do not publish yet)
+
+```bash
+git log <lastTagOrBaseline>..HEAD --pretty=format:'- %s (%h)'
+```
+
+- Group related commits; rewrite subjects for user-facing clarity.
+- Drop noise (merge commits, duplicate WIP messages) unless relevant.
+- Present the bullet list to the maintainer and **wait for explicit approval or edits**.
+
+### 3. Confirm version bump
+
+Default: **`patch`** (`npm version patch --no-git-tag-version`).
+
+Use **`minor`** or **`major`** only if the maintainer requests it.
+
+### 4. Bump version
+
+```bash
+npm version patch --no-git-tag-version   # or minor | major
+```
+
+Read the new version from `package.json`.
+
+### 5. Update README
+
+Prefer the helper script after approval (write bullets to a temp file):
+
+```bash
+npm run release:readme -- --version NEW_VERSION --date YYYY-MM-DD --notes-file /path/to/notes.md
+```
+
+`notes.md` should contain one bullet per line (with or without leading `- `).
+
+If **## Release notes** is missing, add it before **## Contributing** first, then run the script.
+
+Fallback: manually insert at the top of **## Release notes**:
+
+```markdown
+### NEW_VERSION — YYYY-MM-DD
+
+- …
+```
+
+And sync the version badge: `version-NEW_VERSION` in the shields.io img (line ~21).
+
+### 6. Verify CLI
+
+```bash
+npm run test:cli
+```
+
+Stop on failure; do not publish.
+
+### 7. Publish
+
+```bash
+npm publish --access public
+```
+
+If npm prompts for **OTP**, the maintainer enters it in the terminal.
+
+On **403 / cannot publish over previously published versions**: bump with `npm version patch --no-git-tag-version` and retry (each semver can only be published once).
+
+### 8. Report
+
+Tell the maintainer:
+
+- Published version (from `package.json`)
+- https://www.npmjs.com/package/class-ai-agent
+
+**Do not** `git commit`, tag, or push unless the maintainer separately asks.
+
+## Maintainer quick reference
+
+| Step | Command / action |
+|------|------------------|
+| Draft | `git log <tag>..HEAD --pretty=format:'- %s (%h)'` |
+| Approve | Maintainer edits bullets in chat |
+| Bump | `npm version patch --no-git-tag-version` |
+| README | `npm run release:readme -- --version … --notes-file …` |
+| Test | `npm run test:cli` |
+| Publish | `npm publish --access public` |
+
+See also [README — Publishing to npm](../../README.md#publishing-to-npm-maintainers) and [README — Release notes](../../README.md#release-notes).