class-ai-agent 1.4.0 → 1.5.0

package/.agents/workflows/plan.md

@@ -0,0 +1,125 @@
+---
+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/.agents/workflows/publish-npm.md

@@ -0,0 +1,122 @@
+---
+description: "publish-npm"
+---
+# 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 (`.agents/workflows/publish-npm.md` in Cursor; `.agents/workflows/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).

package/.agents/workflows/resume.md

@@ -0,0 +1,106 @@
+---
+description: "Start-of-session — load .agent/SESSION.md and continue prior work"
+---
+
+# /resume — Continue prior work
+
+> "Read the map before you move."
+
+## Purpose
+
+Load cross-tool handoff state and continue work from a previous agent session without re-discovering context.
+
+## When to use
+
+- Starting a new chat on the same feature
+- Switching tools (Cursor ↔ Claude Code ↔ Kiro)
+- User says "continue", "pick up where we left off", or "resume"
+- After pulling a branch that includes an updated `.agent/SESSION.md`
+
+## Prerequisites
+
+- **`.agent/SESSION.md`** exists in the project root
+- If missing: run `npx class-ai-agent` or copy `.agent/SESSION.template.md` → `.agent/SESSION.md`
+
+## Workflow
+
+### Phase 1: Load handoff (read-only first)
+
+Read in this order:
+
+1. **`.agent/SESSION.md`** — goal, done, in progress, next, decisions, gotchas, pointers
+2. **`tasks/todo.md`** — if referenced in Pointers
+3. **`SPEC.md`** or path from Pointers — if in spec/plan/build phase
+
+> Do **not** edit code until Phase 3 plan is stated to the user.
+
+### Phase 2: Sanity check
+
+From SESSION **Gotchas** and **Pointers**, run quick checks when noted:
+
+- `git status` — uncommitted work matches SESSION?
+- Build/test commands listed in Gotchas — run if stale or uncertain
+- Branch matches Pointers
+
+If SESSION reports **blockers** or broken build, surface them before implementing.
+
+### Phase 3: State plan to user
+
+Reply with a short structured summary:
+
+```markdown
+## Resuming
+
+**Goal:** [from SESSION]
+**Phase:** [spec | plan | build | test | review | debug]
+**Last updated:** [Meta date] via [tool/persona]
+
+### Already done
+- ...
+
+### In progress
+- ...
+
+### Next (this session)
+1. ...
+
+### Risks / blockers
+- ...
+```
+
+Ask for confirmation only if SESSION is ambiguous or blockers need a decision.
+
+### Phase 4: Continue workflow
+
+| Phase in SESSION | Command to follow |
+|------------------|-------------------|
+| spec | `/spec` (refine) or `/plan` if spec is done |
+| plan | `/plan` or `/build` if plan exists |
+| build | `/build` |
+| test | `/test` |
+| review | `/review` |
+| debug | `/debug` |
+
+Update **Meta** in `.agent/SESSION.md` when you change phase or tool.
+
+### Phase 5: During work
+
+- After meaningful progress, update SESSION **Done** / **In progress** / **Next**
+- End session with **`/handoff`**
+
+## If SESSION is empty or stale
+
+1. Survey repo: `git log`, `tasks/todo.md`, open PRs
+2. Rebuild SESSION from evidence
+3. Ask user to confirm goal and next steps
+4. Run `/handoff` when aligned
+
+## Output
+
+- Resumption summary (Phase 3)
+- Explicit next action (first item from **Next**)
+- No code changes until plan is stated (unless user asked for a specific fix)
+
+## Next step
+
+Execute the first **Next** item using the appropriate workflow command (`/build`, etc.).

package/.agents/workflows/review.md

@@ -0,0 +1,53 @@
+---
+description: "review"
+---
+# Review Command
+
+## Description
+Perform a thorough code review of specified files or a pull request.
+
+## Usage
+Tell Claude: "Review [file/PR/feature]" or "Do a code review of [changes]"
+
+## Review Checklist
+
+### Code Quality
+- [ ] Code follows style guide (`.agent/rules/code-style.md`)
+- [ ] No unnecessary complexity or duplication
+- [ ] Functions are small and focused (single responsibility)
+- [ ] Variable and function names are descriptive
+
+### Security
+- [ ] No hardcoded secrets or credentials
+- [ ] Input validation is present
+- [ ] Authentication/authorization checks in place
+- [ ] See `.agent/rules/security.md` for full checklist
+
+### Error Handling
+- [ ] Errors are properly caught and handled
+- [ ] Meaningful error messages
+- [ ] No swallowed exceptions
+- [ ] See `.agent/rules/error-handling.md`
+
+### Testing
+- [ ] Unit tests cover new logic
+- [ ] Edge cases are tested
+- [ ] Tests are readable and maintainable
+- [ ] See `.agent/rules/testing.md`
+
+### Database
+- [ ] Queries are optimized (no N+1)
+- [ ] Transactions used where appropriate
+- [ ] See `.agent/rules/database.md`
+
+### API
+- [ ] Endpoints follow REST conventions
+- [ ] Request/response schemas are documented
+- [ ] See `.agent/rules/api-conventions.md`
+
+## Output Format
+Provide feedback as:
+- 🔴 **Critical** — Must fix before merge
+- 🟡 **Warning** — Should fix, potential issue
+- 🟢 **Suggestion** — Nice to have improvement
+- ✅ **Good** — Highlight what's done well

package/.agents/workflows/simplify.md

@@ -0,0 +1,221 @@
+---
+description: "Reduce complexity without changing behavior — code simplification"
+---
+
+# /simplify — Code Simplification
+
+> "Complexity is the enemy of execution."
+
+## Purpose
+
+Simplify code for clarity and maintainability. Reduce complexity **without changing behavior**.
+
+## When to Use
+
+- After `/review` identifies complexity issues
+- When code is hard to understand
+- Before adding new features to tangled code
+- During tech debt cleanup sprints
+
+## Principles
+
+### Chesterton's Fence
+
+> Before removing something, understand why it exists.
+
+Don't delete code just because it looks unnecessary. Investigate:
+- Git history: `git log -p -- path/to/file`
+- Related tests
+- Comments or documentation
+- Ask team members if unsure
+
+### Rule of 500
+
+If a function, file, or class exceeds ~500 lines, it likely needs splitting.
+
+---
+
+## Workflow
+
+### Step 1: Identify Target
+
+```bash
+# Recently modified complex code
+git diff --stat HEAD~10
+
+# Or specify scope
+# "Simplify the OrderService class"
+```
+
+### Step 2: Understand Before Changing
+
+1. **Read the code** — What does it do?
+2. **Check tests** — What behaviors are verified?
+3. **Trace callers** — Who uses this code?
+4. **Note edge cases** — Any special handling?
+
+### Step 3: Identify Opportunities
+
+| Pattern | Simplification |
+|---------|---------------|
+| Deep nesting (> 3 levels) | Guard clauses, extract helpers |
+| Long functions (> 30 lines) | Split by responsibility |
+| Nested ternaries | `if/else` or `switch` |
+| Unclear names | Rename for clarity |
+| Duplicated code | Extract shared function |
+| Dead code | Remove entirely |
+| Complex conditionals | Extract to named function |
+| Magic numbers | Named constants |
+
+### Step 4: Apply Incrementally
+
+**One change at a time:**
+
+```javascript
+// Before: Deep nesting
+function processOrder(order) {
+  if (order) {
+    if (order.items.length > 0) {
+      if (order.status === 'pending') {
+        // ... actual logic buried here
+      }
+    }
+  }
+}
+
+// After: Guard clauses
+function processOrder(order) {
+  if (!order) return;
+  if (order.items.length === 0) return;
+  if (order.status !== 'pending') return;
+
+  // ... actual logic at top level
+}
+```
+
+**Run tests after each change.**
+
+### Step 5: Validate
+
+```bash
+# All tests pass
+npm test
+
+# Build succeeds
+npm run build
+
+# Behavior unchanged (manual check if needed)
+```
+
+### Step 6: If Tests Fail
+
+**Revert immediately.** Don't debug while mid-simplification.
+
+```bash
+git checkout -- .
+```
+
+Then:
+1. Reassess the change
+2. Make a smaller change
+3. Or add missing tests first
+
+---
+
+## Common Simplifications
+
+### Extract Guard Clauses
+
+```javascript
+// Before
+function getDiscount(user) {
+  if (user) {
+    if (user.membership === 'premium') {
+      return 0.2;
+    } else {
+      return 0.1;
+    }
+  }
+  return 0;
+}
+
+// After
+function getDiscount(user) {
+  if (!user) return 0;
+  if (user.membership === 'premium') return 0.2;
+  return 0.1;
+}
+```
+
+### Extract Named Functions
+
+```javascript
+// Before
+const eligibleUsers = users.filter(u => 
+  u.age >= 18 && u.verified && !u.banned && u.subscription !== 'free'
+);
+
+// After
+const isEligible = (user) =>
+  user.age >= 18 && 
+  user.verified && 
+  !user.banned && 
+  user.subscription !== 'free';
+
+const eligibleUsers = users.filter(isEligible);
+```
+
+### Replace Nested Ternary
+
+```javascript
+// Before
+const status = isPaid ? (isShipped ? 'complete' : 'processing') : 'pending';
+
+// After
+function getOrderStatus(isPaid, isShipped) {
+  if (!isPaid) return 'pending';
+  if (!isShipped) return 'processing';
+  return 'complete';
+}
+```
+
+### Remove Dead Code
+
+```javascript
+// Before
+function calculate(a, b) {
+  // const oldResult = legacyCalculate(a, b);  // Commented out
+  const result = a + b;
+  // console.log('Debug:', result);  // Debug log
+  return result;
+}
+
+// After
+function calculate(a, b) {
+  return a + b;
+}
+```
+
+---
+
+## Red Flags
+
+Stop if you find yourself:
+
+- Changing behavior while "simplifying"
+- Unable to explain why code exists
+- Simplifying without tests
+- Making changes across unrelated files
+- Creating new abstractions
+
+---
+
+## Output
+
+- Simpler, clearer code
+- All tests still passing
+- Atomic commits with clear messages
+
+## Next Step
+
+Run `/review` to verify improvements.

package/.agents/workflows/spec.md

@@ -0,0 +1,95 @@
+---
+description: "Spec before code — structured PRD creation for new features"
+---
+
+# /spec — Specification-Driven Development
+
+> "Plan the work, then work the plan."
+
+## Purpose
+
+Create a comprehensive specification document **before** writing any code. This ensures alignment on requirements, constraints, and acceptance criteria.
+
+## Workflow
+
+### Phase 1: Discovery (Ask Questions)
+
+Before generating a spec, gather requirements by asking:
+
+**Scope**
+- What is the objective of this feature?
+- Who are the target users?
+- What problem does this solve?
+
+**Features**
+- What are the core features (MVP)?
+- What are the acceptance criteria for each?
+- What is explicitly out of scope?
+
+**Technical**
+- Any tech stack preferences or constraints?
+- Integration points with existing systems?
+- Performance requirements?
+
+### Phase 2: Generate Specification
+
+After discovery, produce `SPEC.md` with these sections:
+
+```markdown
+# Feature: [Name]
+
+## Objective
+[1-2 sentences describing the goal]
+
+## Target Users
+[Who will use this and why]
+
+## Core Features
+1. [Feature A] — [Acceptance criteria]
+2. [Feature B] — [Acceptance criteria]
+3. [Feature C] — [Acceptance criteria]
+
+## Out of Scope
+- [What we're NOT building in this iteration]
+
+## Technical Approach
+- Tech stack decisions
+- Data models
+- API contracts (if applicable)
+- Integration points
+
+## Code Style
+- Follow rules in `.agent/rules/`
+- [Any feature-specific conventions]
+
+## Testing Strategy
+- Unit tests for: [areas]
+- Integration tests for: [areas]
+- E2E tests for: [critical paths]
+
+## Boundaries
+### Always Do
+- [Non-negotiables]
+
+### Ask First
+- [Decisions requiring approval]
+
+### Never Do
+- [Hard constraints]
+```
+
+### Phase 3: Review & Confirm
+
+- Present the spec to the user
+- Confirm before proceeding to `/plan`
+- Save as `SPEC.md` in project root or `docs/specs/[feature].md`
+
+## Output
+
+- `SPEC.md` — The specification document
+- Clear alignment on what to build
+- **`.agent/SESSION.md`** — Initialize or update: set Meta `phase` to `plan`, **Goal**, **Pointers** → spec path, **Next** → run `/plan`
+
+## Next Step
+
+After spec is approved, run `/plan` to decompose into tasks. Run `/handoff` if ending the session before planning.